Dynamic Audience API

Send recipients

POSThttps://www.postaged.com/api/v1/recipients

Posts the people who meet your criteria to one dynamic campaign. Everything is decided inside this request: each address is verified, the campaign's filters are applied, the budget is checked, and your team is charged. Each result is final when you receive it, except filtered_conditions (see Reasons a recipient was not mailed).

A successful request mails cards and charges your team. Check a payload first with Send test request in the campaign's API / Webhook setup (see Testing).

Authentication

A Full access key. Send it one of three ways:

• AuthorizationheaderPreferred
  Bearer followed by a space and your key.
• X-API-Keyheader
  Your key, for senders that can set a header but not Authorization.
• api_keybody field
  Your key, for senders that cannot set headers.

Never send a key in the URL or a query string. Integration keys and Formulas only keys can't send recipients: they get the same 401 invalid_api_key as a wrong or revoked key.

Request body

• campaign_idstringRequired
  The campaign to mail, from its API / Webhook setup: PA- followed by 6 characters.
• recipientsarray of objectsRequired
  1 to 5,000 recipients. On a Neighborhood Mail campaign, 1 to 250 addresses to mail around.
  • first_namestringOptional
    Given name.
  • last_namestringOptional
    Family name.
  • address_1stringRequired
    Street address. A recipient without it is not mailed (invalid_address); the rest of the request still runs.
  • address_2stringOptional
    Unit or suite.
  • citystringRequired
    City. A recipient without it is not mailed (invalid_address); the rest of the request still runs.
  • statestringRequired
    Two-letter state. A recipient without it is not mailed (invalid_address); the rest of the request still runs.
  • zipstringRequired
    ZIP code. A recipient without it is not mailed (invalid_address); the rest of the request still runs.
  • referencestringOptional
    Your own ID for this recipient, echoed back in its result.
  • birthdaystringOptional
    Birthday, like 3/14 or 1985-03-14.
  • any other keystringOptional
    A custom field, by name. A name you haven't used before becomes a real address book column. Values are stored up to 600 characters. A variable image is an https link sent under the field name shown in the designer. Values sent for formula and AI columns are ignored and counted in computedFieldsIgnored.
• field_typesobjectOptional
  The type of each new custom field, by name: text, number, date, or yes_no. Without one, a new field is Text.
• require_variable_imagesbooleanOptional, default false
  When true, a recipient without a usable variable image is not mailed (variable_image_missing) instead of printing the frame's default image.
• api_keystringOptional
  Your key, only when you cannot send it in a header.

Response 200

One result per recipient, whether or not each was mailed. A recipient's result is final when you receive it, except filtered_conditions (below).

• summaryobject
  received, mailed, and notMailed counts. unparseableTypedValues appears when a custom value didn't fit its column's type (stored exactly as sent). computedFieldsIgnored counts values dropped for formula and AI columns.
• resultsarray of objects
  In the order you sent them.
  • referencestring or null
    Your ID, when you sent one.
  • addressstring
    The address, verified when it could be, otherwise as sent. address_2 is not included.
  • statusstring
    mailed or not_mailed.
  • reasonstring
    Why a recipient was not mailed (below).
  • detailstring
    A sentence you can show to a person. It varies with the case. Branch on status and reason, never on detail.
  • homesFound, homesMailedinteger
    Neighborhood Mail only: homes found around this address, and homes mailed.
  • product_type, postage, mail_by_datestring
    For a mailed recipient on a campaign that isn't Neighborhood Mail: the product's name, standard or first_class, and the mail-by date (YYYY-MM-DD).
  • warningsarray of objects
    Mailed with a fallback (not on Neighborhood Mail): code, field, and detail (codes below).
  • return_address_fallback, return_address_reasonboolean, string
    Present when the recipient's return address couldn't be used, so the design's fallback return address prints (not on Neighborhood Mail).
• results_truncatedboolean
  Present (true) when the full response would have been larger than 4 MB. results then lists only the recipients that were not mailed or were mailed with warnings or return_address_fallback, as many as fit, in the order you sent them. summary still counts every recipient.

Reasons a recipient was not mailed

detail can vary with the case, for example naming the text box or the image. Branch on reason, never on detail.

filtered_conditions isn't final. We add the recipient to the campaign and check them against your filter conditions every day. When they match, we mail them and charge your team then, within the campaign's budget, and the mailing shows in the campaign's Recipients received list. Sending the same address again updates their information.

Warning codes

A mailed recipient carries warnings when a fallback fired. The card still mails.

return_address_reason values

• missing_token_value: a field the return address uses is empty.
• unverified_address: the return address could not be verified.
• verification_limit_reached: this request reached its return address verification limit.

Errors

Each status in the table below means the whole request failed and nothing was mailed or charged. The body is { "code", "message" }. Full tables: Error reference.

A timeout (504) or a dropped connection may come after some recipients were mailed. Send the same payload again: no one is mailed twice. Within 15 minutes of a request that finished, you get its stored response; otherwise recipients already mailed come back as duplicate_recent. If a request times out, wait 20 minutes, then send it again. Recipients it already mailed come back as duplicates; the rest are mailed once.

A body over 4.25 MB can get the hosting platform's own 413, without the { "code", "message" } body.

Limits

• 5,000 recipients per request. On a Neighborhood Mail campaign, 250 addresses and 10,000 homes per request.
• 4.25 MB per request body.
• 4 MB per response. A larger response lists only the recipients that were not mailed or were mailed with a warning, with results_truncated set to true.
• 60 requests per minute per API key, and 60 per minute from one source address. Over the limit: 429 rate_limited with Retry-After: 60.
• A request that sends the same addresses to the same campaign within 15 minutes returns the stored response instead of running again, even when names or custom fields changed, unless that response mailed nobody. No Idempotency-Key header is read.
• An address mailed for a campaign is not mailed again for that campaign for 30 days, or for the campaign's re-send protection window when that is on and longer (90 days by default) (duplicate_recent).
• 10 new custom columns per request, and 50 API-created columns per team. Past either limit, no new column is created and the request still runs. Custom values are stored up to 600 characters.

See also Rate limits and Idempotency and retries.