Poplar

Sync audience members to Poplar for automated direct mail campaigns. Zeotap adds recipients to Poplar audiences with mailing addresses, enabling programmatic postal delivery triggered by your warehouse data.

Prerequisites

• A Poplar account with API access
• A production access token (test tokens only work for the mailings endpoint)
• At least one audience created in the Poplar dashboard

Authentication

Poplar uses Bearer Token authentication.

1. Log in to your Poplar account at heypoplar.com 
2. Navigate to the API Credentials page
3. Click Create New Token and select Production as the token type
4. Copy the generated access token
5. Paste it into the Access Token field in Zeotap

Note: Test tokens (prefixed with test) only work for the mailings endpoint and cannot be used to manage audiences. Always use a production token for Zeotap syncs.

Configuration

No additional configuration fields are required for Poplar. Authentication is handled entirely through the access token.

Target Settings

To find your Audience ID:

1. In Poplar, navigate to Audiences
2. Select the audience you want to sync to
3. Copy the audience ID from the URL or audience details panel
4. Alternatively, use the GET /v1/audiences API endpoint to list all audiences with their IDs

Supported Operations

Sync Modes

Audience Sync Modes

Poplar’s API only supports adding members to audiences. There is no endpoint to remove or update existing audience members. To manage audience membership, use the Poplar dashboard directly.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Each audience member must include at least one identifiable field: a valid address (with address_1 and postal_code), an email, or an identifier. For direct mail delivery, a complete postal address is required.

Default Destination Fields

name, address_1, address_2, city, state, postal_code, email, identifier

These fields map directly to the Poplar audience member API. The address_1, address_2, city, state, postal_code, and name fields are nested into the Poplar address object automatically.

How It Works

Adding Audience Members (Insert / Add Mode)

1. Zeotap sends each row individually to the Poplar Audience API via POST /v1/audience/{audienceId}
2. Address fields (address_1, address_2, city, state, postal_code, name) are assembled into the Poplar address object
3. Optional email, email_sha256, and identifier fields are included at the top level
4. Poplar returns 201 Created for each successfully added member
5. Failed rows are tracked individually with error details

Payload Structure

Each member is sent to Poplar with the following structure:

{
  "address": {
    "name": "Jane Doe",
    "address_1": "123 Main St",
    "address_2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102"
  },
  "email": "jane@example.com",
  "identifier": "cust_12345"
}

Error Handling

• Rows missing all identifiable fields (no address, no email, no identifier) are marked as failed immediately
• HTTP errors from the Poplar API are retried automatically with exponential backoff
• Rate limit responses (429) are retried with appropriate delays
• Each row failure is reported individually in the sync results

Rate Limits

Poplar recommends respecting their rate limits when making API requests. Specific rate limit values are not publicly documented but the platform returns 429 Too Many Requests when limits are exceeded.

Zeotap automatically retries on 429 responses with exponential backoff. Since each audience member is sent individually, high-volume syncs may take longer compared to destinations with batch endpoints.

Best Practices

• Include complete addresses for direct mail campaigns — at minimum address_1, city, state, and postal_code
• Use the identifier field to correlate Poplar audience members with your internal customer IDs
• Create audiences in Poplar first before configuring the sync in Zeotap — the API can only add members to existing audiences
• Use production tokens — test tokens are limited to the mailings endpoint and will fail for audience operations
• Include the name field so Poplar can personalize mail pieces with the recipient’s name
• Use state abbreviations (e.g., CA, NY, TX) for the state field to match USPS formatting

Troubleshooting

Authentication failed: invalid access token

Ensure you are using a production access token, not a test token. Test tokens (prefixed with test) only work for the mailings endpoint. Generate a new production token from the API Credentials page in Poplar.

Audience not found

Verify the Audience ID exists by navigating to Audiences in your Poplar dashboard. The audience must be created in Poplar before you can sync members to it from Zeotap.

Row failed: missing identifiable fields

Each audience member requires at least one of: a valid address (with address_1 and postal_code), an email, or an identifier. Check your field mappings to ensure these fields are populated.

Address validation errors

Poplar may reject addresses that do not pass their validation. Ensure addresses include a valid street address (address_1) and postal code. Use standard USPS abbreviations for state names (e.g., CA instead of California).

Slow sync performance

Poplar’s audience API accepts one member per request. For large audiences (10,000+ members), syncs may take several minutes. This is expected behavior — consider scheduling syncs during off-peak hours.

Rate limit exceeded (429 errors)

Zeotap retries automatically with exponential backoff. If errors persist, reduce the frequency of your sync schedule or contact Poplar support to inquire about rate limit increases for your account.