Batch Operations

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

Endpoint	Batch shape	Max rows	Rate-limit policy
`POST /v1/contacts`	`{ contacts: [...] }`	1000	`contacts.write_batch` (10 / min)
`POST /v1/contacts/batch-delete`	`{ emails: [...] }`	1000	`contacts.write_batch` (10 / min)

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

The HTTP status is 200 even when some rows fail. Per-row failures are surfaced in errors[] so callers can iterate, fix, and re-submit just the bad rows.

{
  "summary": { "inserted": 8, "updated": 2, "failed": 1 },
  "fieldsCreated": ["plan", "creditBalance"],
  "errors": [
    { "email": "bad@", "code": "INVALID_EMAIL", "message": "Email is not RFC-5322 compliant." }
  ],
  "warnings": [
    { "code": "FIELD_NAME_NORMALIZED", "field": "first_name", "from": "first_name", "to": "firstName", "message": "Normalised custom-field name." }
  ]
}

Field	Meaning
`summary.inserted`	Rows that didn’t exist before this request.
`summary.updated`	Rows that existed and were updated.
`summary.failed`	Rows in `errors[]`. The total of `inserted + updated + failed` matches the input length.
`fieldsCreated`	Custom field definitions auto-created on the brand by this request (snake_case / kebab-case → camelCase normalized).
`errors[]`	Per-row failures keyed on `email`. Each carries a stable `code` (e.g. `MISSING_EMAIL`, `INVALID_EMAIL`).
`warnings[]`	Non-fatal observations (field normalization, coercion, duplicate emails collapsed).

`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. See Pagination for reading them back.

curl -X POST https://brew.new/api/v1/contacts \
  -H "Authorization: Bearer $BREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contacts-import-2026-04-08" \
  -d '{
    "contacts": [
      { "email": "jane@example.com", "firstName": "Jane",  "customFields": { "plan": "pro" } },
      { "email": "john@example.com", "firstName": "John",  "customFields": { "plan": "free" } },
      { "email": "bad@",              "firstName": "Bad" }
    ]
  }'

Response (200):

{
  "summary": { "inserted": 1, "updated": 1, "failed": 1 },
  "fieldsCreated": ["plan"],
  "errors": [
    { "email": "bad@", "code": "INVALID_EMAIL", "message": "Email is not RFC-5322 compliant." }
  ],
  "warnings": []
}

TypeScript SDK

const result = await brew.contacts.upsert({
  contacts: [
    { email: 'jane@example.com', firstName: 'Jane', customFields: { plan: 'pro' } },
    { email: 'john@example.com', firstName: 'John', customFields: { plan: 'free' } },
  ],
})

console.log(result.summary)         // { inserted, updated, failed }
console.log(result.fieldsCreated)   // ['plan'] on first sight
for (const err of result.errors) {
  console.error(`row ${err.email} failed: ${err.code}, ${err.message}`)
}

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

curl -X POST https://brew.new/api/v1/contacts/batch-delete \
  -H "Authorization: Bearer $BREW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "jane@example.com",
      "missing@example.com"
    ]
  }'

Response (200):

{
  "deleted": 1,
  "notFound": ["missing@example.com"]
}

Common Per-Row Error Codes

Code	When
`MISSING_EMAIL`	Row in `contacts[]` omitted `email`.
`INVALID_EMAIL`	`email` is not RFC-5322 compliant.
`DUPLICATE_EMAILS_IN_BATCH`	Two rows in the same batch had the same email (only the last write survives). Surfaced as a warning, not an error.
`FIELD_TYPE_MISMATCH`	A custom-field value didn’t match the existing field definition’s type. Re-emit with a coerced value OR delete the field.

Foundational codes from Errors (e.g. 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 column that doesn’t have a fieldDefinitions row on the brand yet, the helper auto-creates one 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 via normalizeAudienceFieldName so snake_case + kebab-case + spaces all converge on the same camelCase column. Normalization events surface in warnings[] as FIELD_NAME_NORMALIZED.

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.

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.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to explore it further with ChatGPT or Claude.

Get started

Overview

Core concepts

Guides

MCP server

CLI

Public API v1

Where It Applies

Partial-Success Contract

`POST /v1/contacts`: Batch Upsert

TypeScript SDK

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

Common Per-Row Error Codes

Auto-Created Field Definitions

Partial Success Design

See Also

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Where It Applies

​Partial-Success Contract

​POST /v1/contacts: Batch Upsert

​TypeScript SDK

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

​Common Per-Row Error Codes

​Auto-Created Field Definitions

​Partial Success Design

​See Also

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Where It Applies

Partial-Success Contract

`POST /v1/contacts`: Batch Upsert

TypeScript SDK

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

Common Per-Row Error Codes

Auto-Created Field Definitions

Partial Success Design

See Also

Need Help?