Send campaigns via the API

Do you want to send your large-scale direct mail campaign sends more programmatically through the API? Well, now you can, too!
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 Documentation: Create Campaign​
First, create your campaign. At a minimum, your campaign needs a name and a schedule_type.
"name": "Demo Campaign",
"schedule_type": "immediate"

Step 2: Add creative

Endpoint: POST 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. If sending a letter, you will also need a from address.
"campaign_id": "campaign_id",
"resource_type": "postcard",
"front": "{{pdf}}",
"back": "{{pdf}}",
"details[size]": "4x6",
"details[mail_type]": "usps_standard_class"

Step 3: Create your upload object

Endpoint: POST Documentation: Create Upload​
Creating your audience, or “upload”, is the next step. This 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.
"campaignId": "{{campaign_id}}",
"requiredAddressColumnMapping": {
"name": "recipient",
"address_line1": "primary line",
"address_zip": "zip_code",
"address_state": "state",
"address_city": "city"

Step 4: Upload your file

Endpoint: POST{{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{{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{{upload_id}} endpoint.
"is_draft": "false"

Step 6: Export failures

Endpoint: POST{{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{{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 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 [email protected].