Contacts
Manage your audience with the API
Keep your contacts in sync with your app. Import thousands at once, tag them, store your own fields, organize them in lists and find exactly who to email, all through one endpoint.
- REST
- JSON
- Bulk up to 10,000 per request
- Lists, tags and fields
- Segments
https://g.sendcorex.com/v1/contactsHow it works
One contact per email
A contact belongs to your account, not to a list. Lists, tags, custom fields and status are attributes of that one contact, so nothing gets duplicated.
One endpoint for everything
Import, tag, query, unsubscribe, manage lists and segments: every action is a command sent to POST /v1/contacts. Up to 20 commands per request.
Built for bulk
Each action takes up to 500 emails and answers email by email. A bad row fails on its own; the rest of the batch goes through.
Get started
Four steps, and only the first one is mandatory before your first request.
- 1
Create an API key
In the dashboard, open Developers → API Keys and create a key. Give it the contact scopes your app needs.
The webmail token does not work here. Contacts use the same dashboard API key you use to send email.
- 2
Choose the scopes
Read-only integrations only need contact:read. A sync that imports and updates needs contact:create and contact:update.
- 3
Define your fields and lists
Create the custom fields you want to store (plan, city, birthday…) and the lists you send to. You can also do this from the dashboard.
- 4
Import and query
Send your contacts with Upsert Contacts, then find them with Query Contacts.
Scopes
Each command needs one scope on the key. When one is missing, only that command fails with MISSING_SCOPE; the rest of the request still runs.
contact:readRead contacts, lists, fields, segments, events and stats.
contact:createCreate lists, fields and segments. Upsert also needs it, to create new contacts.
contact:updateUpdate contacts, tags, status, fields and list membership.
contact:deleteDelete contacts, lists, fields and segments.
The full command-by-command list is in Run Commands. Every command page also says which scope it needs.
The contact
Every read returns contacts in this shape. You only write the parts you care about.
{
"email": "ana@acme.com",
"domain": "acme.com",
"first_name": "Ana",
"last_name": "Costa",
"phone": null,
"company": "Acme",
"locale": "pt-BR",
"timezone": "America/Sao_Paulo",
"source": "checkout",
"status": "subscribed",
"status_reason": null,
"status_at": "2026-10-13T06:05:08.323Z",
"created_at": "2026-10-13T06:05:08.323Z",
"updated_at": "2026-10-14T09:12:40.118Z",
"tags": [
"customer",
"vip"
],
"lists": {
"customers": {
"subscribed": true,
"sendable": true,
"added_at": "2026-10-13T06:05:08.323Z",
"unsubscribed_at": null
}
},
"fields": {
"plan": "pro",
"age": 31,
"city": "São Paulo"
},
"stats": {
"sent_count": 12,
"open_count": 7,
"click_count": 2,
"bounce_count": 0,
"complaint_count": 0,
"open_rate": 0.58,
"click_rate": 0.17,
"first_open_at": "2026-10-13T08:41:02.000Z",
"last_open_at": "2026-10-14T21:03:55.000Z",
"last_click_at": "2026-10-14T21:04:10.000Z",
"last_sent_at": "2026-10-14T20:58:31.000Z"
}
}statusGlobal. A contact that is unsubscribed, bounced, complained or blocked is not sendable in any list.
listsMembership and subscription per list. Someone can leave one list and stay in the others.
sendableSubscribed to the list and with status subscribed. This is what campaigns send to.
statsSends, opens and clicks from tracking. Read-only, and you can filter and sort by them.
Your first request
Import two contacts and read them back, in a single request. Replace SENDCOREX_API_KEY with your API key.
curl -X POST 'https://g.sendcorex.com/v1/contacts' \
-H "Authorization: $SENDCOREX_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"commands": [
{ "command": "upsert_contacts", "args": {
"tags": ["imported"],
"contacts": [
{ "email": "ana@acme.com", "first_name": "Ana", "company": "Acme" },
{ "email": "bob@gmail.com", "first_name": "Bob" }
]
} },
{ "command": "query_contacts", "args": { "where": { "tags": { "has": "imported" } } } }
]
}' You get one result per command. The first tells you how many contacts were created; the second returns them. Run it again and nothing is written: both rows come back with changed: false. The same request in 8 languages is in Upsert Contacts.
Common tasks
Sync signups from your app
Upsert the contact with list_id on every signup. Re-sending the same data writes nothing, so it is safe to call on every login too.
Upsert ContactsHonor an unsubscribe link
Unsubscribe from one list with Set List Subscription, or from everything with Set Status.
Set List SubscriptionFind engaged customers
Query by list, tag and last_open_at, sorted by open_rate. Save it as a segment to reuse it.
Query ContactsExport a list
Walk List Members with sendable_only and select only the fields you need, 5,000 members per page.
List MembersFull reference
Everything marked CMD is a command sent through POST /v1/contacts, up to 20 per request.
Routes
1Contacts
4Search
2Tags, status & fields
5Lists
9- CMDList ListsEvery list, with counters
- CMDGet ListOne list and its counters
- CMDCreate ListYour own id or a generated one
- CMDUpdate ListName, description, custom data
- CMDDelete ListContacts are kept
- CMDList MembersWalk a list, sendable only
- CMDAdd To ListsJoin one or more lists
- CMDRemove From ListsLeave one or more lists
- CMDSet List SubscriptionUnsubscribe from one list