Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Contacts

The people you send marketing mail to, with their subscribe state and custom properties.

A contact is one email address in your team’s list. Each address appears once (case does not matter), and you pick who gets a broadcast with segments and topics. Manage contacts in the dashboard under Audience, or through the API.

What a contact holds

  • email: the address. Creating a second contact with the same address returns 409. An address that can never receive mail (for example example.com, a .test name or a domain with no mail server) returns 422.
  • first_name, last_name.
  • unsubscribed: your team-wide opt-out. While it is true, the contact gets no marketing mail from any of your domains. Only you set it; a recipient’s own unsubscribe never changes it.
  • unsubscribed_domains: read only. The domains the contact left through an unsubscribe link, each with domain_id, name and unsubscribed_at. Mail from those domains skips the contact, and your other domains still reach them. See Unsubscribes.
  • verification_status and verified_at: read only. The result of the contact’s last deep verification, null until it is verified. See Verification.
  • properties: custom values such as plan: "pro" or city: "Berlin". Values are strings or numbers (no nested objects or arrays, which return 422), with at most 100 keys per contact. Properties fill template merge fields and segment filters. PATCH merges them key by key, and a null value removes the key.

Create and read

POST /contacts, GET /contacts, GET /contacts/{id}, PATCH /contacts/{id} and DELETE /contacts/{id}. In {id} you can use the contact’s id or its email address.

curl -X POST "https://api.billionsend.com/contacts" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@acme.com",
    "first_name": "Ana",
    "properties": { "plan": "pro" }
  }'

Add include=properties,topics to GET /contacts or GET /segments/{id}/contacts to get each contact’s properties and topic choices in the same response. POST /contacts/batch/get reads up to 1,000 contacts by id or email in one call, in request order; addresses that match nothing are listed under missing.

PATCH /contacts/{id}/topics sets a contact’s topic choices, and GET /contacts/{id}/topics reads them back with the topic defaults applied.

POST /contacts/{id}/preferences-link returns a link to the contact’s preference page, so you can open it from a settings screen in your product. The link does not expire and lets its holder change that contact’s choices, so give it only to the contact. It opens the team’s default page and opts the contact out of every domain.

Bulk create

POST /contacts/batch takes 1 to 1,000 contacts in one request and writes them together.

on_conflict says what happens when an address already exists or repeats in the batch:

  • error (default): that item fails with 409 (existing) or 422 (repeat).
  • skip: the existing contact is left as it is.
  • upsert: the item is merged into the existing contact. Names only when you send them, properties key by key, segments added, topics updated.

A batch never re-subscribes anyone: unsubscribed: false on a contact who is already unsubscribed is ignored. Use PATCH /contacts/{id} for that.

The x-batch-validation header picks strict (default: one bad item rejects the whole batch) or permissive (valid items are written, failures are listed in errors).

curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
{
  "data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
  "counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
  "errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}

Bulk delete

POST /contacts/batch/remove deletes up to 1,000 contacts by ids or by emails (one of the two) and returns the ones it deleted. Add erase: true to also remove each address from email history, event payloads and API logs. DELETE /contacts/{id}?erase=true does the same for one contact.

CSV import and export

In the dashboard, Audience → Contacts imports a CSV and exports the current view (including a segment, topic or domain filter) back to CSV. The export has an unsubscribed column and an unsubscribed_domains column (* means the whole team). Rows with an address that can never receive mail are skipped. On a paid plan the import dialog can also verify the new addresses, see Verification.

Events

Every change publishes a webhook event: contact.created, contact.updated, contact.deleted, contact.unsubscribed, contact.resubscribed, contact.topic_opt_in and contact.topic_opt_out.

Limits

Free Starter, Pro, Scale
Contacts per team 1,000 No limit

Past the limit, creating a contact returns 403 plan_limit_reached. Existing contacts still update.

Was this page helpful?