API reference
Every Email Marketing API endpoint, with examples.
- GETCheck a key
/marketing/v1/me - POSTCreate or update a contact
/marketing/v1/contacts - POSTCreate or update contacts in a batch
/marketing/v1/contacts/batch - GETList contacts
/marketing/v1/contacts - GETGet a contact
/marketing/v1/contacts/{id} - PATCHUpdate a contact
/marketing/v1/contacts/{id} - POSTUnsubscribe a contact
/marketing/v1/contacts/{id}/unsubscribe - DELETEDelete a contact
/marketing/v1/contacts/{id} - POSTCreate or update a list
/marketing/v1/lists - GETList lists
/marketing/v1/lists - GETGet a list
/marketing/v1/lists/{id} - PATCHUpdate a list
/marketing/v1/lists/{id} - DELETEDelete a list
/marketing/v1/lists/{id} - POSTAdd or remove list members
/marketing/v1/lists/{id}/members - GETList tags
/marketing/v1/tags - GETList segments
/marketing/v1/segments - POSTImport contacts in the background
/marketing/v1/imports - GETGet an import
/marketing/v1/imports/{id} - POSTSend an event
/marketing/v1/events - POSTAdd a webhook endpoint
/marketing/v1/webhooks - GETList webhook endpoints
/marketing/v1/webhooks - GETGet a webhook endpoint
/marketing/v1/webhooks/{id} - PATCHUpdate a webhook endpoint
/marketing/v1/webhooks/{id} - DELETEDelete a webhook endpoint
/marketing/v1/webhooks/{id}
Check a key
/marketing/v1/meThe account a key belongs to and what it may do. Any key can call it: use it to check a key when someone connects your app.
curl -X GET 'https://api.iresendly.com/marketing/v1/me' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "account",
"id": "usr_9f2c",
"name": "Jane's Shop",
"email": "owner@example.com",
"plan": "standard",
"contact_limit": 5000,
"key": {
"id": "6736…",
"name": "SellOrchard",
"scopes": [
"contacts:read",
"contacts:write",
"lists:read",
"lists:write"
]
}
}Create or update a contact
/marketing/v1/contactscontacts:writeCreates the contact, or updates it when one already has the same external_id or email. Tags and lists are added to what the contact already has. A refused address answers 422 with its reason; a full account answers 403 contact_limit.
emailstringrequiredThe contact's email address. New and changed addresses go through the same checks as an import.
external_idstringYour own id for this person, such as a store's customer id. Matched first, so a changed email updates the same contact. Unique in your account.
first_namestringFirst name.
last_namestringLast name.
phonestringPhone number.
subscribedbooleanfalseunsubscribes the contact.true(or leaving it out) subscribes a new contact, but never re-subscribes one who unsubscribed, bounced or complained.custom_fieldsobjectUp to 50 fields. Names start with a letter and use letters, numbers and
_. Values are text, numbers, true/false or null. Merged into the contact's fields.tagsstring[]Tag names to add. Missing tags are created. Matched without regard to case.
list_idsstring[]Lists to add the contact to, by id.
list_keysstring[]Lists to add the contact to, by your own list key (create them with
POST /listsfirst).
curl -X POST 'https://api.iresendly.com/marketing/v1/contacts' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Idempotency-Key: order-1042-customer' \
-H 'Content-Type: application/json' \
-d '{
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"tags": [
"Customer"
],
"list_keys": [
"segment_vip"
],
"custom_fields": {
"orders_count": 3
}
}'{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active",
"subscribed": true,
"tags": [
"Customer",
"VIP"
],
"list_ids": [
"6736a1c4c2a4e51d2f0b7c0a"
],
"custom_fields": {
"orders_count": 3
},
"source": "api",
"created_at": "2026-11-14T10:12:00.000Z",
"updated_at": "2026-11-14T10:12:00.000Z",
"outcome": "created"
}Create or update contacts in a batch
/marketing/v1/contacts/batchcontacts:writeUp to 100 contacts, each with the same fields as a single contact and answered on its own: a refused contact is skipped with its reason, and the rest still go in.
contactsobject[]requiredThe contacts (1–100).
curl -X POST 'https://api.iresendly.com/marketing/v1/contacts/batch' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"contacts": [
{
"email": "jane@example.com",
"external_id": "cus_1042"
},
{
"email": "info@example.com"
}
]
}'{
"object": "batch",
"created": 1,
"updated": 0,
"skipped": 1,
"results": [
{
"index": 0,
"email": "jane@example.com",
"outcome": "created",
"id": "6736a1f0c2a4e51d2f0b7c11"
},
{
"index": 1,
"email": "info@example.com",
"outcome": "skipped",
"reason": "address",
"message": "Role-based addresses aren't accepted"
}
]
}List contacts
/marketing/v1/contactscontacts:readNewest first. Use after with the last id of a page to get the next one.
limitnumber1–100, default 50.
afterstringA contact id: the page after it.
beforestringA contact id: the page before it.
emailstringOnly this email address.
external_idstringOnly this external id.
list_idstringOnly members of this list.
list_keystringOnly members of the list with this key.
tagstringOnly contacts with this tag name.
statusstringactive,unsubscribed,bounced,complained,suppressed,invalidorpending.
curl -X GET 'https://api.iresendly.com/marketing/v1/contacts' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"has_more": false,
"data": [
{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active",
"subscribed": true,
"tags": [
"Customer",
"VIP"
],
"list_ids": [
"6736a1c4c2a4e51d2f0b7c0a"
],
"custom_fields": {
"orders_count": 3
},
"source": "api",
"created_at": "2026-11-14T10:12:00.000Z",
"updated_at": "2026-11-14T10:12:00.000Z"
}
]
}Get a contact
/marketing/v1/contacts/{id}contacts:readOne contact by its iResendly id.
idstringrequiredThe contact id.
curl -X GET 'https://api.iresendly.com/marketing/v1/contacts/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "active",
"subscribed": true,
"tags": [
"Customer",
"VIP"
],
"list_ids": [
"6736a1c4c2a4e51d2f0b7c0a"
],
"custom_fields": {
"orders_count": 3
},
"source": "api",
"created_at": "2026-11-14T10:12:00.000Z",
"updated_at": "2026-11-14T10:12:00.000Z"
}Update a contact
/marketing/v1/contacts/{id}contacts:writeThe same fields and rules as creating one (all optional), plus taking tags and lists off.
idstringrequiredThe contact id.
emailstringThe contact's email address. New and changed addresses go through the same checks as an import.
external_idstringYour own id for this person, such as a store's customer id. Matched first, so a changed email updates the same contact. Unique in your account.
first_namestringFirst name.
last_namestringLast name.
phonestringPhone number.
subscribedbooleanfalseunsubscribes the contact.true(or leaving it out) subscribes a new contact, but never re-subscribes one who unsubscribed, bounced or complained.custom_fieldsobjectUp to 50 fields. Names start with a letter and use letters, numbers and
_. Values are text, numbers, true/false or null. Merged into the contact's fields.tagsstring[]Tag names to add. Missing tags are created. Matched without regard to case.
list_idsstring[]Lists to add the contact to, by id.
list_keysstring[]Lists to add the contact to, by your own list key (create them with
POST /listsfirst).remove_tagsstring[]Tag names to take off.
remove_list_idsstring[]Lists to take the contact off, by id.
remove_list_keysstring[]Lists to take the contact off, by key.
curl -X PATCH 'https://api.iresendly.com/marketing/v1/contacts/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"last_name": "Smith",
"remove_tags": [
"Trial"
]
}'{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"last_name": "Smith",
"phone": null,
"status": "active",
"subscribed": true,
"tags": [
"Customer",
"VIP"
],
"list_ids": [
"6736a1c4c2a4e51d2f0b7c0a"
],
"custom_fields": {
"orders_count": 3
},
"source": "api",
"created_at": "2026-11-14T10:12:00.000Z",
"updated_at": "2026-11-14T10:12:00.000Z"
}Unsubscribe a contact
/marketing/v1/contacts/{id}/unsubscribecontacts:writeAlways works. Only the person can subscribe again, from a sign-up form or the preference page.
idstringrequiredThe contact id.
curl -X POST 'https://api.iresendly.com/marketing/v1/contacts/{id}/unsubscribe' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"email": "jane@example.com",
"external_id": "cus_1042",
"first_name": "Jane",
"last_name": "Doe",
"phone": null,
"status": "unsubscribed",
"subscribed": false,
"tags": [
"Customer",
"VIP"
],
"list_ids": [
"6736a1c4c2a4e51d2f0b7c0a"
],
"custom_fields": {
"orders_count": 3
},
"source": "api",
"created_at": "2026-11-14T10:12:00.000Z",
"updated_at": "2026-11-14T10:12:00.000Z"
}Delete a contact
/marketing/v1/contacts/{id}contacts:writeDeletes the contact from the account.
idstringrequiredThe contact id.
curl -X DELETE 'https://api.iresendly.com/marketing/v1/contacts/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "contact",
"id": "6736a1f0c2a4e51d2f0b7c11",
"deleted": true
}Create or update a list
/marketing/v1/listslists:writeCreates a list. With a key that already exists, that list is renamed and returned instead, so you can call this every time you sync. Lists with a key show Synced from your key's name in iResendly, and only you change their members and name.
namestringrequiredThe list's name.
keystringYour own key for the list, such as a segment id. Unique in the account.
descriptionstringA description.
curl -X POST 'https://api.iresendly.com/marketing/v1/lists' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "VIP customers",
"key": "segment_vip"
}'{
"object": "list",
"id": "6736a1c4c2a4e51d2f0b7c0a",
"key": "segment_vip",
"name": "VIP customers",
"description": null,
"contact_count": 128,
"synced_by": "SellOrchard",
"created_at": "2026-11-14T10:10:00.000Z",
"updated_at": "2026-11-14T10:10:00.000Z",
"outcome": "created"
}curl -X GET 'https://api.iresendly.com/marketing/v1/lists' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"has_more": false,
"data": [
{
"object": "list",
"id": "6736a1c4c2a4e51d2f0b7c0a",
"key": "segment_vip",
"name": "VIP customers",
"description": null,
"contact_count": 128,
"synced_by": "SellOrchard",
"created_at": "2026-11-14T10:10:00.000Z",
"updated_at": "2026-11-14T10:10:00.000Z"
}
]
}Get a list
/marketing/v1/lists/{id}lists:readBy id, or by key as key:<your key>.
idstringrequiredThe list id, or
key:segment_vip.
curl -X GET 'https://api.iresendly.com/marketing/v1/lists/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"id": "6736a1c4c2a4e51d2f0b7c0a",
"key": "segment_vip",
"name": "VIP customers",
"description": null,
"contact_count": 128,
"synced_by": "SellOrchard",
"created_at": "2026-11-14T10:10:00.000Z",
"updated_at": "2026-11-14T10:10:00.000Z"
}Update a list
/marketing/v1/lists/{id}lists:writeRename a list or change its description.
idstringrequiredThe list id, or
key:<your key>.
namestringNew name.
descriptionstringNew description, or null.
curl -X PATCH 'https://api.iresendly.com/marketing/v1/lists/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "VIP (spent over $500)"
}'{
"object": "list",
"id": "6736a1c4c2a4e51d2f0b7c0a",
"key": "segment_vip",
"name": "VIP (spent over $500)",
"description": null,
"contact_count": 128,
"synced_by": "SellOrchard",
"created_at": "2026-11-14T10:10:00.000Z",
"updated_at": "2026-11-14T10:10:00.000Z"
}Delete a list
/marketing/v1/lists/{id}lists:writeOnly lists created through the API. Contacts stay; they just leave the list.
idstringrequiredThe list id, or
key:<your key>.
curl -X DELETE 'https://api.iresendly.com/marketing/v1/lists/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"id": "6736a1c4c2a4e51d2f0b7c0a",
"deleted": true
}Add or remove list members
/marketing/v1/lists/{id}/memberslists:writeUp to 1,000 existing contacts at a time, by id, email or external id. To set a list's members to exactly a set of people, use an import with replace_list_members.
idstringrequiredThe list id, or
key:<your key>.
actionstringrequiredaddorremove.contact_idsstring[]Contact ids.
emailsstring[]Email addresses.
external_idsstring[]Your external ids.
curl -X POST 'https://api.iresendly.com/marketing/v1/lists/{id}/members' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"action": "add",
"external_ids": [
"cus_1042",
"cus_1043"
]
}'{
"object": "list_members",
"list_id": "6736a1c4c2a4e51d2f0b7c0a",
"action": "add",
"requested": 2,
"changed": 2,
"not_found": []
}List segments
/marketing/v1/segmentslists:readSegments are rules kept in iResendly, so the API reads them but doesn't change them. Send your own segments as lists.
curl -X GET 'https://api.iresendly.com/marketing/v1/segments' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"has_more": false,
"data": [
{
"object": "segment",
"id": "seg_71",
"name": "Opened in the last 30 days",
"description": null,
"contact_count": 940,
"created_at": "2026-10-01T09:00:00.000Z"
}
]
}Import contacts in the background
/marketing/v1/importscontacts:writeUp to 10,000 contacts, taken in by iResendly in the background with the same rules as a single contact. Check progress with GET /imports/{id}. With list and replace_list_members, the list ends up with exactly these contacts: how to keep one of your segments in step.
contactsobject[]requiredThe contacts, each like a single contact (1–10,000).
liststringA list id or
key:<your key>. Every imported contact is added to it.replace_list_membersbooleanWith
list: contacts in the list but not in this import leave it (they stay in your contacts). Only for lists created through the API.
curl -X POST 'https://api.iresendly.com/marketing/v1/imports' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"list": "key:segment_vip",
"replace_list_members": true,
"contacts": [
{
"email": "jane@example.com",
"external_id": "cus_1042"
}
]
}'{
"object": "import",
"id": "4b8e0f2a-…",
"status": "queued",
"total": 1,
"processed": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"list_id": "6736a1c4c2a4e51d2f0b7c0a",
"replace_list_members": true,
"removed_from_list": 0,
"skipped_rows": [],
"error": null,
"created_at": "2026-11-14T10:15:00.000Z",
"completed_at": null
}Get an import
/marketing/v1/imports/{id}contacts:readProgress and results. status is queued, running, completed or failed. The first 100 skipped rows are listed with their reason. Imports are kept for 30 days.
idstringrequiredThe import id.
curl -X GET 'https://api.iresendly.com/marketing/v1/imports/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "import",
"id": "4b8e0f2a-…",
"status": "completed",
"total": 1,
"processed": 1,
"created": 1,
"updated": 0,
"skipped": 0,
"list_id": "6736a1c4c2a4e51d2f0b7c0a",
"replace_list_members": true,
"removed_from_list": 4,
"skipped_rows": [],
"error": null,
"created_at": "2026-11-14T10:15:00.000Z",
"completed_at": "2026-11-14T10:15:04.000Z"
}Send an event
/marketing/v1/eventsevents:writeSomething happened in your store or app, and the account's automations should hear about it. The contact is added or updated with the same rules as POST /contacts, then the event runs the matching automation triggers. Each id is taken once: sending it again answers duplicate: true and does nothing.
eventstringrequiredorder.placed,order.refunded,cart.updated,checkout.completed,form.submitted,download.completed,webinar.registered,event.scheduled,course.completedorsubscription.renewing.idstringrequiredYour id for this event, such as the order or cart id plus what happened. Unique per account for 30 days.
emailstringrequiredWho it happened to.
external_idstringYour id for the person (as on contacts).
first_namestringFirst name.
last_namestringLast name.
subscribedbooleanfalseadds a new contact unsubscribed, and no automation starts. Never re-subscribes anyone.tagsstring[]Tag names to add to the contact.
list_keysstring[]Lists to add the contact to, by key.
occurred_atstringWhen it happened (ISO 8601). Defaults to now.
orderobjectorder.placedandorder.refunded:{ id, total, currency, items: [{ title, quantity, price, product_id, variant_id, sku }] }. Orders update the contact's order count, total spent and last order, and start purchase automations.refundobjectorder.refunded:{ amount, full }. A full refund takes the order off the count and stops that order's follow-ups. A refund never adds a contact.cartobjectcart.updated:{ id, total, currency, recover_url, items }. Starts abandoned-cart automations if no order follows;checkout.completedororder.placedcloses the cart.detailsobjectevent.scheduled:{ title, starts_at }for reminder automations. Optionaltitleon the other events.
curl -X POST 'https://api.iresendly.com/marketing/v1/events' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"event": "order.placed",
"id": "order-1042-placed",
"email": "jane@example.com",
"external_id": "cus_1042",
"order": {
"id": "1042",
"total": 49.5,
"currency": "USD",
"items": [
{
"title": "Mango ice",
"quantity": 2,
"price": 24.75,
"product_id": "p_88"
}
]
}
}'{
"object": "event",
"id": "order-1042-placed",
"event": "order.placed",
"duplicate": false,
"contact_id": "6736a1f0c2a4e51d2f0b7c11",
"enrolled": 1
}Add a webhook endpoint
/marketing/v1/webhookswebhooks:manageWhere iResendly sends contact.unsubscribed, contact.bounced and contact.complained events. Up to 5 endpoints per account. The answer includes the signing_secret for checking signatures.
endpointstringrequiredYour https address.
eventsstring[]requiredThe events to send.
curl -X POST 'https://api.iresendly.com/marketing/v1/webhooks' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"endpoint": "https://store.example.com/webhooks/iresendly",
"events": [
"contact.unsubscribed",
"contact.bounced",
"contact.complained"
]
}'{
"object": "webhook",
"id": "6736b2e0c2a4e51d2f0b7d01",
"endpoint": "https://store.example.com/webhooks/iresendly",
"events": [
"contact.unsubscribed",
"contact.bounced",
"contact.complained"
],
"status": "enabled",
"disabled_reason": null,
"created_at": "2026-11-14T11:00:00.000Z",
"signing_secret": "whsec_…"
}curl -X GET 'https://api.iresendly.com/marketing/v1/webhooks' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "list",
"has_more": false,
"data": [
{
"object": "webhook",
"id": "6736b2e0c2a4e51d2f0b7d01",
"endpoint": "https://store.example.com/webhooks/iresendly",
"events": [
"contact.unsubscribed"
],
"status": "enabled",
"disabled_reason": null,
"created_at": "2026-11-14T11:00:00.000Z"
}
]
}Get a webhook endpoint
/marketing/v1/webhooks/{id}webhooks:manageOne endpoint, with its signing secret.
idstringrequiredThe webhook id.
curl -X GET 'https://api.iresendly.com/marketing/v1/webhooks/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "webhook",
"id": "6736b2e0c2a4e51d2f0b7d01",
"endpoint": "https://store.example.com/webhooks/iresendly",
"events": [
"contact.unsubscribed"
],
"status": "enabled",
"disabled_reason": null,
"created_at": "2026-11-14T11:00:00.000Z",
"signing_secret": "whsec_…"
}Update a webhook endpoint
/marketing/v1/webhooks/{id}webhooks:manageChange the address or events, or turn it off and on (status: enabled or disabled).
idstringrequiredThe webhook id.
endpointstringNew address.
eventsstring[]New events.
statusstringenabledordisabled.
curl -X PATCH 'https://api.iresendly.com/marketing/v1/webhooks/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"status": "disabled"
}'{
"object": "webhook",
"id": "6736b2e0c2a4e51d2f0b7d01",
"endpoint": "https://store.example.com/webhooks/iresendly",
"events": [
"contact.unsubscribed"
],
"status": "disabled",
"disabled_reason": "Disabled manually",
"created_at": "2026-11-14T11:00:00.000Z"
}Delete a webhook endpoint
/marketing/v1/webhooks/{id}webhooks:manageStops all events to it straight away.
idstringrequiredThe webhook id.
curl -X DELETE 'https://api.iresendly.com/marketing/v1/webhooks/{id}' \
-H 'Authorization: Bearer irm_xxxxxxxxx'{
"object": "webhook",
"id": "6736b2e0c2a4e51d2f0b7d01",
"deleted": true
}