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
POSThttps://g.sendcorex.com/v1/contacts

How 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. 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. 2

    Choose the scopes

    Read-only integrations only need contact:read. A sync that imports and updates needs contact:create and contact:update.

  3. 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. 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:read

    Read contacts, lists, fields, segments, events and stats.

  • contact:create

    Create lists, fields and segments. Upsert also needs it, to create new contacts.

  • contact:update

    Update contacts, tags, status, fields and list membership.

  • contact:delete

    Delete contacts, lists, fields and segments.

i

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"
  }
}
status

Global. A contact that is unsubscribed, bounced, complained or blocked is not sendable in any list.

lists

Membership and subscription per list. Someone can leave one list and stay in the others.

sendable

Subscribed to the list and with status subscribed. This is what campaigns send to.

stats

Sends, 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 Contacts

Honor an unsubscribe link

Unsubscribe from one list with Set List Subscription, or from everything with Set Status.

Set List Subscription

Find engaged customers

Query by list, tag and last_open_at, sorted by open_rate. Save it as a segment to reuse it.

Query Contacts

Export a list

Walk List Members with sendable_only and select only the fields you need, 5,000 members per page.

List Members

Full reference

Everything marked CMD is a command sent through POST /v1/contacts, up to 20 per request.