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#
- 1Open Settings → API keys
In Email Marketing.
- 2Click 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.
- 3Copy the key
It starts with
irm_and is shown once. Paste it into the app you're connecting.
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"]}'| What | Details |
|---|---|
| Address | https://api.iresendly.com/marketing/v1 |
| Rate limit | 10 requests a second (5 on a free trial). Headers ratelimit-limit, ratelimit-remaining and ratelimit-reset show where you are. |
| Retries | Send an Idempotency-Key header on a POST: the same key and body within 24 hours returns the first answer instead of running twice. |
| Keys | Server-side only. Browsers can't call the API. |
How contacts are handled#
- A contact is matched by your
external_idfirst, 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.
{
"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"
}
}sourceisunsubscribe_link,bounce,complaint,salesforce,apioriresendly.contactis null if the address isn't a contact.- Every message is signed the Standard Webhooks way: check the
webhook-signatureheader with the endpoint's signing secret, for example with thestandardwebhooksorsvixlibraries.webhook-idstays 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.
| Status | name | Means |
|---|---|---|
| 401 | missing_api_key | No key in the request. |
| 403 | invalid_api_key | The key doesn't exist or was revoked. |
| 403 | wrong_product_key | A Developer API key (irs_…) or an older account key. |
| 403 | insufficient_scope | The key's access doesn't cover this; details.required names the permission. |
| 403 | no_access | Email Marketing isn't active on the account. |
| 403 | contact_limit | The plan's contact limit is reached. |
| 404 | not_found | No such contact, list or import in this account. |
| 409 | conflict | Another contact already has that email or external id. |
| 409 | idempotency_conflict | The Idempotency-Key was used with a different request. |
| 422 | validation_error | A field is wrong, or the address was refused (details.reason: address, domain, blocked or bounced). |
| 429 | rate_limit_exceeded | Too many requests; wait for retry-after. |
Settings → API keys also shows the last 50 requests made with your keys, kept for 30 days.