Skip to content

Email Marketing API

Keep your contacts, lists and tags up to date from a store or app. Designing and sending stay in iResendly.

The Email Marketing API lets another system, such as your store, a CRM or a platform you sell through, add and update your contacts, put them on lists and tag them. Campaigns, automations and sending stay in iResendly: API keys can't send email or change campaigns.

API keys#

  1. 1
    Open Settings → API keys

    In Email Marketing.

  2. 2
    Click New key

    Name it after the app it's for, and choose its access: Contacts sync (contacts, lists, tags, events and webhooks) or Read only.

  3. 3
    Copy the key

    It starts with irm_ and is shown once. Paste it into the app you're connecting.

Note
Developer API keys (irs_…) are for sending email from your code, and don't work here. Make one key per app, so you can revoke them one at a time.

Making requests#

Send the key in the Authorization header, and JSON bodies with Content-Type: application/json.

curl -X POST 'https://api.iresendly.com/marketing/v1/contacts' \
  -H 'Authorization: Bearer irm_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"email":"jane@example.com","external_id":"cus_1042","tags":["Customer"]}'
WhatDetails
Addresshttps://api.iresendly.com/marketing/v1
Rate limit10 requests a second (5 on a free trial). Headers ratelimit-limit, ratelimit-remaining and ratelimit-reset show where you are.
RetriesSend an Idempotency-Key header on a POST: the same key and body within 24 hours returns the first answer instead of running twice.
KeysServer-side only. Browsers can't call the API.

How contacts are handled#

  • A contact is matched by your external_id first, then by email, so someone who changes their email stays one contact.
  • New and changed addresses go through the same checks as an import: role addresses (like info@), fake and disposable addresses, domains that can't receive mail, and addresses that bounced or complained before are refused, with the reason.
  • Unsubscribes win. A contact who unsubscribed, bounced or complained is never made active again through the API; only they can do that. The answer says so with kept_status.
  • New contacts count towards your plan's contact limit. At the limit, new contacts are refused with contact_limit; updates keep working.
  • Contacts added through the API show the key's name as where they came from, and start your sign-up automations like any new contact.

Keeping your segments in step#

Create one list per segment with POST /lists and your own key, then either add and remove members as people change, or send everyone in the segment with an import and replace_list_members. Lists with a key show Synced from in iResendly, and can't be renamed or have members changed there, so nothing you send is undone by hand. Campaigns and automations can use them like any list.

Events and automations#

Send POST /events when something happens in your store, such as an order, a cart or a form, and the account's automations start like they do for Shopify or BigCommerce stores: purchase follow-ups, abandoned carts, first-order and milestone emails, and the order count and total spent on each contact. Give each event your own id; sending the same one again does nothing.

Webhooks: hearing about opt-outs#

Add an endpoint with POST /webhooks (or in Settings → API keys) and iResendly tells you straight away when someone unsubscribes, bounces or marks an email as spam, so you can stop emailing them from your side too. Unsubscribes from email links, bounce and complaint reports, Salesforce opt-outs and your own API unsubscribes all count; each change is sent once.

contact.unsubscribed
{
  "type": "contact.unsubscribed",
  "created_at": "2026-11-14T12:00:00.000Z",
  "data": {
    "email": "jane@example.com",
    "contact": {
      "id": "6736a1f0c2a4e51d2f0b7c11",
      "email": "jane@example.com",
      "external_id": "cus_1042"
    },
    "source": "unsubscribe_link",
    "reason": "One-click unsubscribe from campaign email"
  }
}
  • source is unsubscribe_link, bounce, complaint, salesforce, api or iresendly. contact is null if the address isn't a contact.
  • Every message is signed the Standard Webhooks way: check the webhook-signature header with the endpoint's signing secret, for example with the standardwebhooks or svix libraries. webhook-id stays the same across retries, so you can skip repeats.
  • Answer with any 2xx status within 15 seconds. Failed messages are retried after 5 seconds, 5 minutes, 30 minutes, 2, 5, 10 and 10 hours. An endpoint that keeps failing for 5 days is turned off.
  • Settings → API keys shows each endpoint's deliveries for 30 days, and can send a test event or a past message again.

Errors#

Errors have the same shape everywhere: { statusCode, name, message }, sometimes with details.

StatusnameMeans
401missing_api_keyNo key in the request.
403invalid_api_keyThe key doesn't exist or was revoked.
403wrong_product_keyA Developer API key (irs_…) or an older account key.
403insufficient_scopeThe key's access doesn't cover this; details.required names the permission.
403no_accessEmail Marketing isn't active on the account.
403contact_limitThe plan's contact limit is reached.
404not_foundNo such contact, list or import in this account.
409conflictAnother contact already has that email or external id.
409idempotency_conflictThe Idempotency-Key was used with a different request.
422validation_errorA field is wrong, or the address was refused (details.reason: address, domain, blocked or bounced).
429rate_limit_exceededToo many requests; wait for retry-after.

Settings → API keys also shows the last 50 requests made with your keys, kept for 30 days.

Still stuck? Write to us and we'll reply by email.Contact ussupport@iresendly.com