Mailing

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.

Create Mailer

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.

Headers

Name	Type	Description
Authorization*	string	Bearer <Test/Prod Access Token>
Content-Type*	string	application/json

Request Body

Name	Type	Description
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)

201: Created Mailer has successfully been created

{
    "id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "campaign_id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "creative_id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "merge_tags": null,
    "state": "processing",
    "front_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "back_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "pdf_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "total_cost": "0.00",
    "address": null,
    "send_at": null,
    "created_at": "YYYY-MM-DDThh:mm:ssZ"
}

400: Bad Request Incorrect values are being passed in the body

{
    "error": {
        "name": "ValidationError",
        "message": "recipient[postal_code] must 3 or more characters long"
    }
}

403: Forbidden Incorrect or missing auth hearers

{
    "error": "Unauthorized"
}

Recipient Object

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.

Key	Value Type	Desc.
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

Fetch Mailing

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.

Path Parameters

Name	Type	Description
mailing_id*	string	ID of the mailing.

Headers

Name	Type	Description
Authorization*	string	Bearer <Production Access Token>

200: OK Returns mailer details

{
    "id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "campaign_id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "creative_id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "merge_tags": null,
    "state": "production",
    "front_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "back_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "pdf_url": "https://app.heypoplar.com/preview/xxxxx-xxxxx-xxxxx-xxxxx",
    "total_cost": "0.00",
    "address": {
        "name": "Jim Halpert",
        "company": null,
        "address_1": "13831 Calvert St",
        "address_2": "# 1A",
        "city": "Van Nuys",
        "state_name": "CA",
        "postal_code": "91401"
    },
    "send_at": null,
    "created_at": "YYYY-MM-DDThh:mm:ssZ"
}

404: Not Found mailing_id is incorrect or does not exist

{
    "error": {
        "name": "NotFound",
        "message": "Mailing not found"
    }
}

403: Forbidden Incorrect or missing auth header

{
    "error": "Unauthorized"
}

Creative Previews

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).

Mailer Format	Front Image	Back Image	PDF
Postcard	Yes	Yes	Yes
Letter	Yes (first page only)	No	Yes