# 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

<mark style="color:green;">`POST`</mark> `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.<br>

#### Headers

| Name                                            | Type   | Description                                                       |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer <mark style="color:blue;">\<Test/Prod Access Token></mark> |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json                                                  |

#### Request Body

| Name                                           | Type   | Description                                                                                                                                                                                                                                                    |
| ---------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| campaign\_id<mark style="color:red;">\*</mark> | string | An ID corresponding to a campaign.                                                                                                                                                                                                                             |
| creative\_id                                   | string | <p>An ID corresponding to the creative to use for the mailing. <br><br><em>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.</em></p> |
| 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 | <p>An ISO8601 formatted date indicating when the mailing should be sent. This must be a future date.<br><br>If a date is not provided, the mailing will be triggered immediately. </p>                                                                         |
| recipient<mark style="color:red;">\*</mark>    | object | An object containing the mailing address and/or email of the recipient *(see example below)*                                                                                                                                                                   |

{% tabs %}
{% tab title="201: Created Mailer has successfully been created" %}

```json
{
    "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"
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect values are being passed in the body" %}

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

{% endtab %}

{% tab title="403: Forbidden Incorrect or missing auth hearers" %}

```javascript
{
    "error": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

### 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:

<figure><img src="https://content.gitbook.com/content/xfN4IIBsOUuqBd0ERnDW/blobs/cVO8pAFuTZOsoRMxPaJx/Screen%20Shot%202022-05-16%20at%202.41.06%20PM.png" alt=""><figcaption></figcaption></figure>

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.                                                                                              |
| ---------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- |
| <p><code>full\_name</code><br><em>or</em><br><code>first\_name</code><br><code>last\_name</code></p> | string     | <p>Optional<br><br><em>If not provided, "Current Resident" will appear on address block</em></p>   |
| `company`                                                                                            | string     | Optional                                                                                           |
| `email`                                                                                              | string     | Optional                                                                                           |
| `address_1`                                                                                          | string     | Required                                                                                           |
| `address_2`                                                                                          | string     | <p>Optional<br><br><em>Apt/Suite/Unit number can be included with address\_1 if necessary</em></p> |
| `city`                                                                                               | string     | Required                                                                                           |
| `state`                                                                                              | string     | Required                                                                                           |
| `postal_code`                                                                                        | string     | Required                                                                                           |
| `identifier`                                                                                         | string     | <p>Optional<br><br><em>A unique identifier used for tracking purposes</em> </p>                    |

## Fetch Mailing

<mark style="color:blue;">`GET`</mark> `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.&#x20;

#### Path Parameters

| Name                                          | Type   | Description        |
| --------------------------------------------- | ------ | ------------------ |
| mailing\_id<mark style="color:red;">\*</mark> | string | ID of the mailing. |

#### Headers

| Name                                            | Type   | Description                                                          |
| ----------------------------------------------- | ------ | -------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer *<mark style="color:blue;">\<Production Access Token></mark>* |

{% tabs %}
{% tab title="200: OK Returns mailer details" %}

```json
{
    "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"
}
```

{% endtab %}

{% tab title="404: Not Found mailing\_id is incorrect or does not exist" %}

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

{% endtab %}

{% tab title="403: Forbidden Incorrect or missing auth header" %}

```javascript
{
    "error": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

### 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.&#x20;

{% hint style="warning" %}
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.
{% endhint %}

All preview images are 600px wide PNG files with variable height (based on the creative format used).&#x20;

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