Guide: Create and Book API Campaigns

Do you want to automate creating and booking bulk campaigns? Here is our step by step guide to which API requests to use.

This guide assumes you have created your design templates. If you haven’t already done this please got to the templates section of your dashboard, create your templates, and remember to take note of your template id.

The guide also assumes you know how to authenticate and make API requests. Samples in this guide will be in curl. You can learn more about the API in our documentation pages.

Step 1

If you don’t already have data in the platform we will want to create a recipient group and feed recipients into it. So lets use the following endpoint.
https://dash.stannp.com/api/v1/groups/new

curl https://dash.stannp.com/api/v1/groups/new \
-d "name=My Group"

The API will respond with a group id for the newly created group. Now we need to feed recipients into the group one by one.
https://dash.stannp.com/api/v1/recipients/new

curl https://dash.stannp.com/api/v1/recipients/new \
-d "group_id=1" \
-d "on_duplicate=update" \
-d "firstname=Steve" \
-d "lastname=Parish" \
-d "address1=Unit 12 Taw Trade Park" \
-d "address2=Braunton Road" \
-d "city=Barnstaple" \
-d "postcode=EX31 1JZ" \
-d "country=GB" \
-d "voucher=GT4523"

We can continue looping through these requests until we have all our recipients imported.

Step 2

Now we know our group id and template id we can create a bulk campaign. We are also using an add-on code to send using first class postage.
https://dash.stannp.com/api/v1/campaigns/create

curl https://dash.stannp.com/api/v1/campaigns/create \
-d "name=My Campaign" \
-d "type=a5-postcard" \
-d "template_id=12345" \
-d "group_id=12345" \ 
-d "addons=FIRST_CLASS"

The API will respond with a newly created campaign id for our campaign.

You can request various add-on codes from us if you need to automate more bespoke jobs. Just get in touch with your account manager, or speak to our friendly team via webchat or on 01271 344507. 

Step 3

Now we need to review and approve the campaign, so lets produce a sample using this endpoint.
https://dash.stannp.com/api/v1/campaigns/sample

curl https://dash.stannp.com/api/v1/campaigns/sample
-d "id=123"

This will produce a sample PDF file in the response which is an example of how the mail piece will look, laid up with a sample from our data set.

If we are happy with this then we can approve the campaign.
https://dash.stannp.com/api/v1/campaigns/approve

curl https://dash.stannp.com/api/v1/campaigns/approve
-d "id=123"

Step 4

All that is left to do is to book in the campaign. Lets first check how much it will cost;
https://dash.stannp.com/api/v1/campaigns/cost

curl https://dash.stannp.com/api/v1/campaigns/cost
-d "id=123"

The response is a breakdown of the cost. We are interested in the “net” value because we are booking with the balance on our Stannp account, so the net cost will be deducted from our balance.
https://dash.stannp.com/api/v1/campaigns/book

curl https://dash.stannp.com/api/v1/campaigns/book \
-d "id=123" \
-d "send_date=2019-09-28" \ 
-d "use_balance=true"

That’s it, a simple 4 step process. We’ve booked our first programmatic API campaign, ready to be sent by the Stannp.com team.

We hope you find our  Guide to Creating and Booking an API campaign useful.

For more useful hints, tips, guides and info you can find us on Twitter, Facebook and LinkedIn, or speak to your account manager.

Stannp.com #WeKeepYouPosted