Override cancellation window
Table of Contents
Anytime you place an order it’s good to understand the cancellation policy. By default, new accounts have a 5-minute cancellation window. Within that time frame, you can cancel mailings, free of charge. Once the cancellation time window has passed for a postcard, self-mailer, letter, or check, the mailing is no longer cancelable.
Can I programmatically override my cancellation window?
Using a custom send date in your Lob request enables you to override your default cancelation window and set a specific date and time for which you want a mail piece to go into production.
Why is this important?
Some clients may want to create a campaign today with Lob, but have it actually mailed in 2 weeks. This provides them the time to QA and make sure everything is in order. Others may need to dictate when certain mail pieces go out after a trigger, e.g., two weeks after a shopper abandons their cart, a postcard is sent telling them that the item is now on sale. Either way, this feature enables customers to dictate when a mail piece goes into production if a static cancellation window is not sufficient for their needs. They can do this for each specific mail piece and can customize as needed. If this is not used in the request, it will use the default cancellation window as it is not required.
How do we (programmatically) solve this problem?
If a custom send date is desired, you will have to send either a date or a timestamp of the desired send date. If you send a simple date (YYYY-MM-DD) it will evaluate to midnight UTC of that date. If you don't need to send a custom send date, simply do not include it in the payload—or pass null—to use your default cancellation window.
In the code sample below, we want mail to go into production on July 1st at 6:00 am PST which is 2:00 pm UTC.
To do this our send date is "2022-07-01T14:00:00"
TypeScript
import {Configuration, Postcard, PostcardsApi, PostcardEditable, CountryExtended } from "@lob/lob-typescript-sdk"
async function demo() {
const config: Configuration = new Configuration({
username: "<YOUR_TEST_KEY>"
})
const postcardData : PostcardEditable = {
to: {
name: "Harry Zhang",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
from: {
name: "Leore Avidar",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us
},
front: "https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf",
back: "https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf",
send_date: "2022-07-01T14:00:00"
}
try {
const result : Postcard = await new PostcardsApi(config).create(postcardData)
return result
} catch (err: any) {
console.error(err)
}
}
demo().then((result)=> console.log(result)).catch()
Delete
Python
import lob
lob.api_key = "<YOUR_TEST_KEY>"
postcard = lob.Postcard.create(
description = "First Postcard",
to_address = {
"name": "Harry Zhang",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107"
},
from_address = {
"name": "Leore Avidar",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
front = "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back = "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
merge_variables = {
"name": "Harry"
},
send_date = "2022-07-01T14:00:00"
)
print(postcard)
Delete
Ruby
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "<TEST_API_KEY>")
pp lob.postcards.create(
description: "First Postcard",
to: {
name: "Harry Zhang",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
from: {
name: "Leore Avidar",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
merge_variables: { name: "Harry" },
front: "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back: "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
send_date: "2022-07-01T14:00:00"
) Delete
PHP
<?php require __DIR__ . '/vendor/autoload.php';
$lob = new \Lob\Lob('<TEST_API_KEY');
$postcard = $lob->postcards()->create(array(
"description" => "First Postcard",
"to[name]" => "HARRY ZHANG",
"to[address_line1]" => "210 KING STREET",
"to[address_city]" => "SAN FRANCISCO",
"to[address_state]" => "CA",
"to[address_zip]" => "94107",
"from[name]" => "LEORE AVIDAR",
"from[address_line1]" => "210 KING STREET",
"from[address_city]" => "SAN FRANCISCO",
"from[address_state]" => "CA",
"from[address_zip]" => "94107",
"front" => "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
"back" => "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
"merge_variables[name]" => "Harry",
"send_date" => "2022-07-01T14:00:00"
));
print_r($postcard);
?> Delete
Java
package com.company.app;
// HashMap for Java 8 and below
// import java.util.HashMap;
import java.util.Map;
import com.lob.Lob;
import com.lob.model.Address;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("<TEST_API_KEY>");
Map<String, String> mergeVariables = Map.of(
"name", "Harry"
);
// FOR JAVA VERSIONS 8 AND BELOW:
// Map<String, String> merge_variables = new HashMap<String, String>() {{
// put("name", "Harry");
// }};
try {
LobResponse<Postcard> response = new Postcard.RequestBuilder()
.setDescription("First Mail piece")
.setTo(
new Address.RequestBuilder()
.setName("HARRY ZHANG")
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFrom(
new Address.RequestBuilder()
.setName("LEORE AVIDAR" )
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFront("<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>")
.setBack("<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>")
.setMergeVariables(mergeVariables)
.setSendDate("2022-07-01T14:00:00")
.create();
Postcard postcard = response.getResponseBody();
System.out.println(postcard);
} catch (Exception err) {
System.out.println("Error on postcard creation: " + err);
}
}
} Delete