Mailing
Last updated
Last updated
Poplar Mailing endpoints enable you to easily target individual customers with timely 1-1 event driven mailings. Each API request you make is associated with a recipient, campaign & creative.
POST
https://api.heypoplar.com/v1/mailing
https://api.heypoplar.com/v1/mailing
This endpoint allows you to trigger a mailer for a given campaign. Mailings can only be triggered for active campaigns containing creative artwork. The API will return an error if the campaign is not active, or if creative has not been uploaded.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
When creating a mailing you are required to provide a recipient
object. A custom Data Guide can be found at the bottom of each creative's page:
This should include the keys listed below. If you are unable to provide mailing addresses, we offer the ability to append an address based on email address. This must be enabled for your account and in your campaign settings. Including additional fields will not increase the match rate. If we are not able to find a match, you will not be billed.
GET
https://api.heypoplar.com/v1/mailing/:id
https://api.heypoplar.com/v1/mailing/:id
This endpoint allows you to query the status of a triggered mailing.
When you create or fetch a mailing, the response will include URLs linking to the image and PDF previews. After initial creation of the mailing, you can access the images or PDFs directly through the URLs. Authentication is not required, but URLs expire 30 days after creation.
URLs may be available before the images are available. If that is the case, you will get 202: Accepted when you attempt to access the image. The 'Retry After' HTTP header will indicate when you should retry fetching.
If a mailing is invalid, suppressed, part of a holdout, etc. you will always get a 202, because a preview is not generated.
Image and PDF previews may not be available at the same time.
All preview images are 600px wide PNG files with variable height (based on the creative format used).
Key | Value Type | Desc. |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Mailer Format | Front Image | Back Image | |
---|---|---|---|
Authorization*
string
Bearer <Test/Prod Access Token>
Content-Type*
string
application/json
campaign_id*
string
An ID corresponding to a campaign.
creative_id
string
An ID corresponding to the creative to use for the mailing. If not provided, the default creative will launch. If no default is set, the platform will randomly alternate between all active creatives under the campaign to A/B test.
merge_tags
object
An object containing a custom set of key/value pairs that map to any custom merge tags used in dynamic HTML creative
send_at
string
An ISO8601 formatted date indicating when the mailing should be sent. This must be a future date. If a date is not provided, the mailing will be triggered immediately.
recipient*
object
An object containing the mailing address and/or email of the recipient (see example below)
full_name
or
first_name
last_name
string
Optional If not provided, "Current Resident" will appear on address block
company
string
Optional
email
string
Optional
address_1
string
Required
address_2
string
Optional Apt/Suite/Unit number can be included with address_1 if necessary
city
string
Required
state
string
Required
postal_code
string
Required
identifier
string
Optional A unique identifier used for tracking purposes
mailing_id*
string
ID of the mailing.
Authorization*
string
Bearer <Production Access Token>
Postcard
Yes
Yes
Yes
Letter
Yes (first page only)
No
Yes