---
title: Contacts
description: 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](/docs/concepts/segments) and [topics](/docs/concepts/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](/docs/concepts/unsubscribes).
- `verification_status` and `verified_at`: read only. The result of the contact's last deep verification, `null` until it is verified. See [Verification](/docs/concepts/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.

```sh
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`).

```sh
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" }]'
```

```json
{
  "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](/docs/concepts/verification).

## Events

Every change publishes a [webhook](/docs/concepts/webhooks) 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.
