Skip to main content
Brew accepts batch writes on the contacts routes so agents and back-end importers can upsert / delete many rows in a single request without burning the per-request rate-limit budget. Batches are partial-success-safe: one bad row doesn’t fail the whole call.

Where It Applies

Single-row upserts use POST /v1/contacts with a different body shape and the higher-rate contacts.write_single policy (100 / min). Single-row deletes use DELETE /v1/contacts/{email}. Choose the shape that matches your workload: 100/min × 1 row = 100 contacts/min; 10/min × 1000 rows = 10,000 contacts/min.

Partial-Success Contract

When any rows fail, including when every row fails, the batch upsert returns 207 instead of 200. Failures are surfaced in errors[] so callers can fix and re-submit the rejected rows.
For a completed JSON batch upsert response, inserted + updated + failed equals the number of input rows. Two duplicate rows contribute failed: 2. Use summary.failed to count rejected rows.

POST /v1/contacts: Batch Upsert

Up to 1000 rows per request. email is the merge key; missing or malformed emails land in errors[]. Custom fields auto-create field definitions on the brand on first sight, typed from the batch. If another request creates the same new field at the same moment, the first definition wins, and this request’s values are converted to its type or refused with FIELD_TYPE_MISMATCH, exactly as if this request had been sent second. Create the field first with POST /v1/fields to pin its type. See Pagination for reading them back. The addresses below are synthetic fixtures. Replace them with test contacts you control.
Assume John exists, Jane is new, and the brand has no plan field definition. The response is 207 because bad@ fails validation:

TypeScript SDK

POST /v1/contacts/batch-delete: Batch Delete

Up to 1000 emails per request. The endpoint is idempotent: deleting a non-existent email surfaces in notFound[], not as an error.
Assuming Jane exists and missing@brewmail.dev does not, the response is 200:

Contact Imports

POST /v1/contacts/import (JSON rows) and POST /v1/contacts/import-csv (CSV text) follow the same partial-success contract. Each also records an Import History batch and returns its importId. Add Contacts covers when to use each, consent, and the preview and skip modes.
  • Counts. summary.total counts the submitted JSON contacts or parsed CSV data rows. It equals inserted + updated + failed + skipped.
  • Partial results. Inspect errors and warnings before retrying. Each failed row has its own error with a 1-based row: contacts[row - 1] for JSON, or the CSV data row, counting neither the header nor blank lines. Fix and retry only failed rows; successful writes have already landed.
  • Skipped rows. With onConflict: "skip", each existing contact counts as skipped. In a CSV, missing or invalid addresses and earlier duplicates are counted as skipped too. CSV_ROW_SKIPPED warnings name the first 100 skipped rows; one additional warning counts the rest. Column-wide and aggregate warnings have no row index.
  • Duplicates. A CSV processes the last row for each repeated address; inspect its result before assuming it was saved. A JSON batch fails every row of a repeated address, so send each contact once.
  • Managed columns. A column Brew manages, such as Created At or Validation Status, isn’t imported. The response names it in a CSV_COLUMN_IGNORED warning.
  • Field names. Brew stores each custom field under its folded camelCase name. A JSON key sent in another spelling, such as team_size, is stored as teamSize with a FIELD_NAME_NORMALIZED warning that carries original and normalized.
  • Two spellings of one field. Keys that fold to one field, such as plan and Plan, would lose a value, so Brew refuses them with FIELD_NAME_COLLISION:
    • A single POST /v1/contacts answers 422 and writes nothing. param names the second key, and details carries field and keys.
    • A batch POST /v1/contacts or POST /v1/contacts/import fails that row with an errors[] entry (code: FIELD_NAME_COLLISION, field: customFields.<key>). The other rows are written.
    • PATCH /v1/contacts/{email} and MCP update_contact answer 422 and write nothing.
    • POST /v1/contacts/import-csv and MCP import_contacts_csv answer 422 with param: mapping when two columns land on one custom field, before any row is read, dryRun included. Remap one column in mapping, or leave it out with "".
This CSV import answers 207: row 3 has a value its field rejects, and row 2 has no email.

Common Per-Row Error Codes

Email matching trims surrounding whitespace and ignores case. Deduplicate those normalized addresses before retrying. To unsubscribe a contact, submit one unambiguous row with the address and top-level subscribed: false to POST /v1/contacts. A rejected duplicate group applies no subscription changes. Foundational codes from Errors (for example RATE_LIMITED, INVALID_REQUEST) only ever apply to the whole request, never to individual rows.

Auto-Created Field Definitions

When a batch upsert references a custom field the brand doesn’t have yet, Brew creates the field definition before the write. The new column shows up immediately in:
  • the contacts page (filterable / sortable / searchable),
  • the audience builder,
  • GET /v1/fields,
  • POST /v1/contacts/search with { "logic": "and", "filters": [{ "field": "plan", "operator": "equals", "value": "pro" }] }.
Field names are normalized to one camelCase field. Plan and PLAN are plan, and team_size and Team Size are teamSize. Property Names has the full rule. A key stored under its normalized name adds a FIELD_NAME_NORMALIZED warning with original and normalized. Two keys in one row that normalize to one field, such as plan and Plan, would lose a value. That row fails with FIELD_NAME_COLLISION (field: customFields.<key>), and the other rows are still written. Send one of the keys, or rename one so it names a different field.

Partial Success Design

Batch writes report aggregate counts and failed rows so invalid data does not block valid contacts. The contract and response shape are above; see API design notes for the rationale. If your workflow requires all-or-nothing, validate and stage the input before calling the endpoint. Do not infer which successful rows were newly inserted from aggregate counts and delete them, because a batch can also update existing contacts.
  • Idempotency: set Idempotency-Key on the batch so a retry doesn’t replay 1000 rows.
  • Rate limits: contacts.write_batch is 10/min (vs single at 100/min); plan accordingly.
  • Pagination: for reading back the imported rows.
  • Errors: full error catalog for the foundational request-level codes.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.