# Mass deletion setup
{% hint style="danger" %}
#### Please contact [Lob support](https://www.lob.com/contact) if you need help with live mail pieces already created. Note:
* If the [cancellation window](https://help.lob.com/print-and-mail/building-a-mail-strategy) has already elapsed, canceling is not possible.
* If not elapsed, you will need to provide a list of the resource IDs you would like to have canceled.
* Submitting deletion requests via Support is not a suitable replacement for making deletion requests on your own.
{% endhint %}
## Overview
Having a mass delete system in place is essential to avoid unnecessary costs, save time, and protect customer relationships when a campaign is mistakenly triggered. This feature allows you to cancel large amounts of mail associated with a specific campaign, identified by a batch ID, without disrupting other outgoing mail.
In this tutorial, we’ll show you how to [leverage Lob’s metadata](#mass-deletion-using-lob-metadata) property or manage mail campaign information [within your infrastructure](#utilize-your-own-infrastructure-7) for efficient mass deletion. This helps you quickly stop unintended campaigns before they go to print, preventing early or incorrect mail from reaching customers.
## Prerequisites
* [A Lob account and API key](https://docs.lob.com/#tag/Getting-Started)
* A large number of mail pieces needing to be canceled quickly
* The mail pieces have **not** been sent to printers
## Mass deletion using Lob metadata
The recommended approach for identifying batches of mail sent through Lob is to use the [metadata property](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/using-metadata) with a unique key-value pair. Below is an example of how to create a single mail piece that includes metadata with a `batch_id` set to “NEWYORK2022”. The `batch_id` can be anything you want as long as it is unique to the batch, is a maximum length of 500 characters and is used for all mail pieces in the batch.
Create a config using your `LOB_API_KEY` found in the [Lob dashboard](https://dashboard.lob.com/settings/api-keys). Find more on idempotency keys [here](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12).
{% tabs %}
{% tab title="TypeScript" %}
```typescript
const config: Configuration = new Configuration({
username: "test_XXXXXXXXX",
});
const postCardExample: PostcardEditable = {
to: {
company: "HARRY ZHANG",
address_line1: "210 KING STREET",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
},
from: {
company: "LEORE AVIDAR",
address_line1: "185 BERRY ST",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
},
front = "Front HTML",
back = "Back HTML",
metadata: {
batch_id: "NEWYORK2022"
}
};
const postcardsApi = new PostcardsApi(config);
const postcard = await postcardsApi.create(postCardExample);
```
{% endtab %}
{% tab title="Python" %}
```python
import lob
lob.api_key = "test_XXXXXXXXX"
postcard = lob.Postcard.create(
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": "185 BERRY STREET",
"address_line2": "SUITE 6100",
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
front = "Front HTML",
back = "Back HTML",
metadata = {
"batch_id": "NEWYORK2022"
}
)
```
{% endtab %}
{% tab title="Ruby" %}
```ruby
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "test_XXXXXX")
newPostcard = lob.postcards.create(
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: "185 BERRY STREET",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107"
},
front: "Front HTML",
back: "Back HTML",
metadata: {
"batch_id": "NEWYORK2022"
}
)
```
{% endtab %}
{% tab title="PHP" %}
```php
$lob = new \Lob\Lob('test_XXXXXX');
$postcard = $lob->postcards()->create(array(
"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]" => "185 BERRY STREET",
"from[address_line2]" => "SUITE 6100",
"from[address_city]" => "SAN FRANCISCO",
"from[address_state]" => "CA",
"from[address_zip]" => "94107",
"front" => "Front HTML",
"back" => "Back HTML",
"metadata[batch_id]" => "NEWYORK2022"
));
```
{% endtab %}
{% tab title="Java" %}
```java
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_XXXXXXXX");
Map metaData = Map.of(
"batch_id", "NEWYORK2022"
);
try {
LobResponse response = new Postcard.RequestBuilder()
.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("Front HTML")
.setBack("Back HTML")
.setMetadata(metaData)
.create();
Postcard postcard = response.getResponseBody();
System.out.println(postcard);
} catch (Exception err) {
System.out.println("Error on postcard creation: " + err);
}
}
}
```
{% endtab %}
{% endtabs %}
In order to delete all postcards from the NEWYORK2022 campaign, use the list function and pass a metadata object with a `batch_id` key set to NEWYORK2022. This returns a list of all NEWYORK2022 campaign postcards, loop over each one and pass the postcard id into the cancel function.
To see the full list of acceptable parameters in the list, visit the [docs](https://docs.lob.com/#section/Metadata).
{% tabs %}
{% tab title="TypeScript" %}
```typescript
const config: Configuration = new Configuration({
username: "test_XXXXXXXXX",
});
const postcardsApi = new PostcardsApi(config);
const listOfPostcards = await postcardsApi.list(
undefined,
undefined,
undefined,
undefined,
undefined,
{ batch_id: "NEWYORK2022" }
);
for (let postcard of listOfPostcards) {
await postcardsApi.cancel(postcard.id);
}
```
{% endtab %}
{% tab title="Python" %}
```python
import lob
lob.api_key = "test_XXXXXXXXXXXXXX"
list_of_postcards = lob.Postcard.list(metadata={"batch_id": "NEWYORK2022"})
for i in list_of_postcards.data:
lob.Postcard.delete(i.id)
```
{% endtab %}
{% tab title="Ruby" %}
```ruby
require 'lob.rb'
require 'pp'
require 'json'
lob = Lob::Client.new(api_key: "test_XXXXXXXXXX")
list = lob.postcards.list(metadata: {"batch_id": "NEWYORK2022"})
data = list['data']
data.each do |item|
begin
lob.postcards.destroy( item['id'])
rescue Lob::InvalidRequestError => e
obj = JSON.parse(e.json_body)
pp obj['error']['message']
end
end
```
{% endtab %}
{% tab title="PHP" %}
```php
$metadata = ["batch_id" => "NEWYORK2022"];
$list = $lob->postcards()->all(array('metadata' => $metadata));
foreach($list['data'] as $item) {
try {
$lob->postcards()->delete($item['id']);
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "\n";
}
}
```
{% endtab %}
{% tab title="Java" %}
```java
import java.util.Map;
import java.util.HashMap;
import com.lob.Lob;
import com.lob.model.PostcardCollection;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("test_XXXXXXXXX");
Map metaData = Map.of(
"batch_id", "NEWYORK2022"
);
Map params = new HashMap<>();
params.put("metadata", metaData);
try {
LobResponse listResp = Postcard.list(params);
PostcardCollection list = listResp.getResponseBody();
for(int i=0; i deleteResponse = Postcard.delete(list.getData().get(i).getId());
} catch (Exception err) {
System.out.println("Error: " + err);
}
}
} catch (Exception err) {
System.out.println("Error: " + err);
}
}
}
```
{% endtab %}
{% endtabs %}
## Mass deletion utilizing your own infrastructure
If you plan to save details about individual mail pieces in your database, consider including an identifier for the campaign as well. In the example below, we create a new postcard and upon successful completion, we store details in our database.
Create a config using your `LOB_API_KEY` found in the lob dashboard.
{% hint style="success" %}
For extra resiliency, you can pass in the batch id via metadata (see above example), as well as store it locally as seen below.
{% endhint %}
{% tabs %}
{% tab title="TypeScript" %}
```typescript
const config: Configuration = new Configuration({
username: "test_XXXXXXXXX",
});
const postCardExample: PostcardEditable = {
to: {
name: "HARRY ZHANG",
address_line1: "210 KING STREET",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
},
from: {
name: "LEORE AVIDAR",
address_line1: "185 BERRY ST",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
}
};
const postcardsApi = new PostcardsApi(config);
const postcard = await postcardsApi.create(postCardExample);
/* Save to your database with the postcard.id and a unique group id */
```
{% endtab %}
{% tab title="Python" %}
```python
import lob
lob.api_key = "test_XXXXXXXXX"
postcard = lob.Postcard.create(
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": "185 BERRY ST",
"address_line2": "SUITE 6100",
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
front = "Front HTML for Postcard",
back = "Back HTML for Postcard"
)
# Save to your database with the postcard.id and a unique group id
```
{% endtab %}
{% tab title="Ruby" %}
```ruby
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "test_XXXXXX")
newPostcard = lob.postcards.create(
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: "185 BERRY ST",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107"
},
front: "Front HTML",
back: "Back HTML"
)
//Save to your database with the postcard.id and a unique group id
```
{% endtab %}
{% tab title="PHP" %}
```php
$lob = new \Lob\Lob('test_XXXXXX');
$postcard = $lob->postcards()->create(array(
"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]" => "185 BERRY STREET",
"from[address_line2]" => "SUITE 6100",
"from[address_city]" => "SAN FRANCISCO",
"from[address_state]" => "CA",
"from[address_zip]" => "94107",
"front" => "Front HTML",
"back" => "Back HTML"
));
/* Save to your database with the postcard.id and a unique group id */
```
{% endtab %}
{% tab title="Java" %}
```java
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_XXXXXXXX");
try {
LobResponse response = new Postcard.RequestBuilder()
.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("Front HTML")
.setBack("Back HTML")
.create();
/* Save to your database with the postcard.id and a unique group id */
} catch (Exception err) {
System.out.println("Error on postcard creation: " + err);
}
}
}
```
{% endtab %}
{% endtabs %}
To mass delete, we fetch a list of mail pieces from our database using a unique id for our campaign and loop over all the mail pieces to cancel them.
{% tabs %}
{% tab title="TypeScript" %}
Fetch the list ids from your database using your unique group id
```typescript
const config: Configuration = new Configuration({
username: LOB_API_KEY,
});
const postcardsApi = new PostcardsApi(config);
for (let item of dbdata) {
await postcardsApi.cancel(item.id);
/* Remove the record from your database */
}
```
{% endtab %}
{% tab title="Python" %}
Fetch the list ids from your database using your unique group id
```python
import lob
lob.api_key = "test_XXXXXXXXXX"
for i in dbdata:
lob.Postcard.delete(i.id)
/* Remove the record from your database */
```
{% endtab %}
{% tab title="Ruby" %}
Fetch the list ids from your database using your unique group id
```ruby
dbdata.each do | item |
begin
lob.postcards.destroy( item['id'])
# Remove the record from your database
rescue Lob::InvalidRequestError => e
obj = JSON.parse(e.json_body)
pp obj['error']['message']
end
end
```
{% endtab %}
{% tab title="PHP" %}
Fetch the list ids from your database using your unique group id
```php
foreach($dbdata as $item) {
try {
$lob->postcards()->delete($item['id']);
/* Remove the record from your database */
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "\n";
}
}
```
{% endtab %}
{% tab title="Java" %}
Fetch the list ids from your database using your unique group id
```java
import java.util.Map;
import java.util.HashMap;
import com.lob.Lob;
import com.lob.model.PostcardCollection;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("test_XXXXXXXXX");
for(int i=0; i deleteResponse = Postcard.delete(list.getData().get(i).getId());
/* delete record from your database */
} catch (Exception err) {
System.out.println("Error: " + err);
}
}
}
}
```
{% endtab %}
{% endtabs %}