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 returns207 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.
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.
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.totalcounts the submitted JSON contacts or parsed CSV data rows. It equalsinserted + updated + failed + skipped. - Partial results. Inspect
errorsandwarningsbefore retrying. Each failed row has its own error with a 1-basedrow: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_SKIPPEDwarnings 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 AtorValidation Status, isn’t imported. The response names it in aCSV_COLUMN_IGNOREDwarning. - 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 asteamSizewith aFIELD_NAME_NORMALIZEDwarning that carriesoriginalandnormalized. - Two spellings of one field. Keys that fold to one field, such as
planandPlan, would lose a value, so Brew refuses them withFIELD_NAME_COLLISION:- A single
POST /v1/contactsanswers422and writes nothing.paramnames the second key, anddetailscarriesfieldandkeys. - A batch
POST /v1/contactsorPOST /v1/contacts/importfails that row with anerrors[]entry (code: FIELD_NAME_COLLISION,field: customFields.<key>). The other rows are written. PATCH /v1/contacts/{email}and MCPupdate_contactanswer422and write nothing.POST /v1/contacts/import-csvand MCPimport_contacts_csvanswer422withparam: mappingwhen two columns land on one custom field, before any row is read,dryRunincluded. Remap one column inmapping, or leave it out with"".
- A single
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/searchwith{ "logic": "and", "filters": [{ "field": "plan", "operator": "equals", "value": "pro" }] }.
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.Related
- Idempotency: set
Idempotency-Keyon the batch so a retry doesn’t replay 1000 rows. - Rate limits:
contacts.write_batchis 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:- Self-Service Tools
- Talk to Our Team
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.