Skip to content
Sendocado

Contacts

The people you email: what a contact holds, how to add many at once, and how to export or erase one.

View as Markdown

What a contact holds

  • email: the address, stored in lowercase. It never changes; to move someone to a new address, create a new contact.
  • first_name, last_name: used by the {{ first_name }} and {{ last_name }} merge tags.
  • timezone: an IANA zone like Europe/London. Campaign send windows use it before the campaign’s or project’s zone.
  • tags: labels like trial or customer, up to 50 per contact.
  • attributes: key and value pairs like plan = pro, up to 100 per contact. Keys use lowercase letters, digits and underscores.
  • is_unsubscribed, is_blocked: read from the address’s history, see Unsubscribes and blocks.

Add contacts from your app

Create one contact when someone signs up. The answer is 409 contact_exists when the address is already in the project.

Create a contact
curl -X POST "https://sendocado.com/api/v1/projects/$PROJECT_ID/contacts" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "maya@example.com",
  "first_name": "Maya",
  "last_name": "Patel",
  "timezone": "Europe/London",
  "tags": ["trial"],
  "attributes": {
    "plan": "trial",
    "company": "Northwind"
  }
}'

To create or update many at once, send up to 1,000 contacts to the batch route. It is all or nothing: one bad contact refuses the whole batch, and the error names its index. For a contact that already exists, a null field keeps what is stored, tags are added, and attributes are set.

Create or update contacts
curl -X PUT "https://sendocado.com/api/v1/projects/$PROJECT_ID/contacts/batch" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "email": "maya@example.com",
      "first_name": "Maya",
      "last_name": null,
      "timezone": null,
      "tags": ["customer"],
      "attributes": {
        "plan": "pro"
      }
    },
    {
      "email": "leo@example.com",
      "first_name": "Leo",
      "last_name": "Martin",
      "timezone": "Europe/Paris",
      "tags": ["trial"],
      "attributes": {}
    }
  ]
}'

A new contact, or one whose tags or attributes change, joins every live campaign whose audience it now matches within seconds.

Find contacts

List contacts with one of search (email and name), tag or email. To see which tags and attribute keys are in use, for building an audience, list the contact tags and attribute keys.

History and privacy

  • Activity lists every email sent to the address and what happened to it.
  • Export returns everything held about a contact in one JSON document, for a subject-access request.
  • Erasure deletes the contact and everything sent to the address. The address stays unsubscribed or blocked, without the address itself, so it can never be mailed again by mistake.

Deleting a contact only removes the contact: its unsubscribes and blocks stay.

See the Contacts reference for every route.