External Audiences

An external audience lets a campaign fetch recipients from your own HTTP feed. Each feed item identifies both the person and the individual row to send.

Contact identity and row identityCopy Anchor Link

Use externalId for the contact's identity in your system. Mailcrate uses it to find or create the contact, so multiple feed rows for the same person should carry the same externalId.

Use idempotencyKey for the identity of one feed row and its delivery. It must distinguish rows that should produce separate deliveries, even when those rows share an email address and externalId.

For example, two notices for the same person use one contact identity and two row identities:

{
  "items": [
    {
      "email": "alice@example.com",
      "externalId": "customer-42",
      "idempotencyKey": "invoice-1001",
      "data": { "invoiceNumber": "1001" }
    },
    {
      "email": "alice@example.com",
      "externalId": "customer-42",
      "idempotencyKey": "invoice-1002",
      "data": { "invoiceNumber": "1002" }
    }
  ]
}

Those rows create two deliveries. Public delivery responses and delivery.* webhooks expose their canonical campaignRecipientKey values as external:invoice-1001 and external:invoice-1002. Keep the external: prefix when storing or filtering by that field; it is part of the value. The feed's externalId is returned separately as nullable externalReferenceId, and delivery.sent returns the row's data separately as nullable templateData.