Send campaigns via the Campaigns API

This functionality is in beta. Please reach out to [e-mail] or your Account Manager with any feedback or feature requests.

Use our Campaigns API to send your large-scale direct mail campaign sends more programmatically.

When creating campaigns, you’ll interact with 3 main models: campaigns, creatives, and uploads.

• The campaigns model is used to set up high-level information about your campaign

• The creatives model is used for uploading artwork and artwork settings for your campaign

• The uploads model is used to build your audience and configure any recipient-level details for your campaign

Follow the steps below to create your first campaign in the API.

Step 1: Create your campaign

Endpoint: POST api.lob.com/v1/campaigns Documentation: Create Campaign

First, create your campaign. At a minimum, your campaign needs a name and a schedule_type and a use_type if one has not been declared at the account level. It is highly recommended that a cancel_window_campaign_minutes is provided given it will allow you to cancel the campaign within the specified window if needed.

{ 
    "name": "Demo Campaign",
    "schedule_type": "immediate",
    "use_type": "marketing",
    "cancel_window_campaign_minutes": "120"
}

Step 2: Add creative

Endpoint: POST api.lob.com/v1/creatives Documentation: Create Creatives

The next step is to create your creative object that will be associated with the campaign. You can only associate a single creative with a campaign. You are required to add a campaign_id, resource_type, and any requirements for your selected resource_type. This payload is subject to change depending on your form factor. See examples below.

Postcard

{ 
    "campaign_id": "campaign_id",
    "resource_type": "postcard",
    "front": "{{pdf || url || template_id}}",
    "back": "{{pdf || url || template_id}}",
    "details": {
        "size": "4x6",
        "mail_type": "usps_standard_class",
    }
}

Letter

Note: the details section has additional optional parameters, see docs for more info.

{ 
    "campaign_id": "campaign_id",
    "resource_type": "letter",
    "file": "{{pdf || url || template_id}}",
    "from": {
        "name": "Lob.com",
        "address_line1": "210 King St.",
        "address_city": "San Francisco",
        "address_state": "CA",
        "address_zip": "94107"
    }
    "details": {
        "color": true,
        "mail_type": "usps_standard_class"
    }
}

Step 3: Map columns from your data file to specified fields

Endpoint: POST api.lob.com/v1/uploads Documentation: Create Upload

Uploading your audience data file is the next step. Step 3 can be done prior to Step 2 as well. For more information on how to best structure your upload for Steps 3 and 4, visit our campaign audience guide.

If using optionalAddressColumnMapping, all fields must be specified (which means unused fields must be declared with a null value). If you're using an HTML template, double check that you have provided all keys and values for mergeVariableColumnMapping, if not all merge variables are mapped, your campaign will not be executable when it comes time to send.

{
    "campaignId": "{{campaign_id}}",
    "requiredAddressColumnMapping": {
        "name": "recipient",
        "address_line1": "address_line1",
        "address_city": "address_city",
        "address_state": "address_state",
        "address_zip": "address_zip"
    },
    "optionalAddressColumnMapping": {
        "address_line2": "address_line2",
        "company": null,
        "address_country": null
    },
    "mergeVariableColumnMapping": {
        "date": "date",
        "firstName": "firstName",
        ...
        "qr_url": "qr_url"
    },
    "metadata": {
        "columns": [
            "email"
        ]
    }
}

Step 4: Upload your file

Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/file Documentation: Upload File

After creating your upload object, you can now upload your file as a byte stream (binary file).

{ 
    "file": "{{file.csv}}"
}

Step 5: Execute your campaign

Endpoint: POST api.lob.com/v1/campaigns/{{campaign_id}}/send Documentation: Send Campaign

Finally, you can execute your campaign! To see the status of your mail pieces as they are created, use the GET api.lob.com/v1/uploads/{{upload_id}} endpoint.

{
   "is_draft": "false"
}

Step 6: Get failed addresses

Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/exports Documentation: Create Export

First, let us know that you would like to create a failure export. Your response will include an export ID, which will be used to retrieve the export URL in the next step.

{
   "type": "failures"
}

Endpoint: GET api.lob.com/v1/uploads/{{upload_id}}/exports/{{export_id}} Documentation: Retrieve Export

You can then retrieve the S3 URL of the export from the GET response above. Your export will include row-level details on why each record failed.

Step 7: Cancel your campaign

Endpoint: DELETE api.lob.com/v1/campaigns Documentation: Delete Campaign

As long as your campaign cancellation window has not passed, you can cancel your campaign using our DELETE route on the campaigns endpoint.

And that's it! If you have any questions, feel free to reach out to your Customer Success Manager, or to [e-mail].