Contacts API

Endpoints

Check a list before importing

POST /v1/contacts/verify checks 1–10,000 addresses without creating contacts or sending mail. Send { "emails": ["person@yourdomain.com"] }. Checks include syntax, domain mail routing, disposable/role-address signals, this project's known bounce or complaint history, and addresses known across Email Bump not to exist (known_to_bounce) or that our email provider won't deliver to (cant_be_delivered). This is not mailbox verification: ok means nothing known against the address, not proof that it exists or that you have consent.

Each result includes score, reasons and provider. Read guidance for the check's limitations. Never treat verification as permission to send purchased or unsolicited lists.

The dashboard CSV importer can apply verify_mode=basic (exclude undeliverable) or strict (also exclude risky). off skips those checks, but malformed and reserved-domain addresses are still rejected. A lookup failure alone never excludes a row; strict mode can still reject it for a separate established risk. Import is a dashboard session operation, not a public /v1/contacts/import endpoint.

Create or update a contact

This endpoint is an upsert. A new email creates a contact (201); an existing email updates the fields you send and leaves the rest untouched (200). The created flag in the response tells you which happened, so an import or sync loop is safe to re-run without handling conflicts. On an update, attributes are merged — keys you send win, keys you don't send stay, and an explicit null removes one. A field this endpoint doesn't take (say list_id instead of list_ids, or tags) is a 400 naming the valid fields, never silently dropped.

curl -X POST https://emailbump.com/api/v1/contacts \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "first_name": "Jamie",
    "company": "Acme",
    "attributes": { "plan": "pro" },
    "list_ids": ["5b3a0ea3-5c58-423e-92ff-0aaac7be0af3"]
  }'

{
  "created": true,
  "contact": {
    "id": "5fef0867-b292-46ca-8371-e24d8575576c",
    "email": "jamie@example.com",
    "first_name": "Jamie",
    "company": "Acme",
    "attributes": { "plan": "pro" },
    "subscribed": true,
    "email_status": "active",
    "created_at": "2026-07-21T19:56:38Z"
  }
}

Update a contact

PATCH /v1/contacts/{id} changes only the fields you send. It takes the same profile fields as create, minus email, plus two the upsert doesn't:

curl -X PATCH https://emailbump.com/api/v1/contacts/5fef0867-b292-46ca-8371-e24d8575576c \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "company": "Acme Corp", "attributes": { "plan": "enterprise" } }'

DELETE /v1/contacts/{id} removes the contact and its event history, and returns 204.

List & search

Filter by status (subscribed / unsubscribed for consent, or active / hard_bounced / soft_bounced / complained for deliverability; any other value is a 400) and search (email, name or company; not case-sensitive). To look one contact up by address, use email — an exact match that returns one contact or an empty set.

curl "https://emailbump.com/api/v1/contacts?search=jamie&status=subscribed&limit=25" \
  -H "Authorization: Bearer ebk_your_key"

curl "https://emailbump.com/api/v1/contacts?email=jamie@example.com" \
  -H "Authorization: Bearer ebk_your_key"

Export to CSV

GET /v1/contacts/export answers with the whole audience as a file — text/csv, not JSON. It supports status and search filters, has no pagination, and streams, so a large audience starts arriving before all of it has been read. Unlike the contacts list, status=subscribed exports only subscribed contacts whose email_status is active.

They combine, and they combine with each other: a list scoped to a segment scoped to a search is one file.

curl "https://emailbump.com/api/v1/contacts/export?status=subscribed" \
  -H "Authorization: Bearer ebk_your_key" \
  -o contacts.csv

# One list, everyone on it, including who never confirmed
curl "https://emailbump.com/api/v1/contacts/export?list_id=5b3a0ea3-5c58-423e-92ff-0aaac7be0af3" \
  -H "Authorization: Bearer ebk_your_key" \
  -o newsletter.csv

The columns are email, first_name, last_name, company, phone, country, city, timezone and subscribed, then the state we maintain — email_status, unsubscribed_at, created_at, id — followed by list_status for a list-scoped export and custom-attribute columns. Export selects the first 200 distinct attribute keys alphabetically across the project, then excludes keys that collide with the profile or four state columns. It is not a complete attribute backup for projects above that limit. Objects and arrays are written as JSON text; strings, numbers and booleans are written plainly. Missing or null values are empty cells.

In the dashboard the same file is Export CSV: on Contacts it exports what the page is showing, search box and status filter included; on a list, that list; and on the Segments row menu, that segment.

Subscribe / unsubscribe

Toggle marketing consent. Unsubscribing also sets unsubscribed_at and puts the address on the project's Do not email list. Subscribing lifts this project's unsubscribe from that list, so only call it on fresh, explicit consent. It is refused with a 400 for someone who marked your email as spam — only a teammate can clear that, from the dashboard — and it cannot clear a bounce, which also stays unmailable until a teammate clears it. unsubscribed_at and the contact.subscribed / contact.unsubscribed webhook only change when consent does, so unsubscribing someone twice keeps the time they left.

curl -X POST https://emailbump.com/api/v1/contacts/5fef0867-b292-46ca-8371-e24d8575576c/unsubscribe \
  -H "Authorization: Bearer ebk_your_key"