API Introduction

Brew API Overview

Brew’s REST API gives you secure, programmatic access to core email marketing features. Use the API to:

Send transactional emails using your published email templates
Trigger automations with custom events and payloads
Import contacts in bulk with custom fields
Update and delete contacts by email address

The API is designed for easy integration with your backend, CRM, or internal tools. All API endpoints are secured with HTTPS and use Bearer token authentication.

Quick Start

Get up and running in under 5 minutes:

Get your API key

In Brew, go to Settings → API and click Create API Key. Give it a descriptive name like “Production App”. All API requests require authentication. You can use either header format:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Keep your API key secure. Never share it publicly or use it in client-side code. Store it in environment variables and never commit API keys to version control.

Test your connection

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://brew.new/api/send/transactional

This returns API documentation if your key is valid.

Start building

Explore the API endpoints and build your integration. Send your first transactional email, create contacts, or trigger automations.

Base URL and Authentication

Base URL: https://brew.new/api All requests must include your API key via one of these headers:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Brew’s API follows REST conventions using standard HTTP methods:

GET - Retrieve data
POST - Create new resources
PATCH - Update existing resources
DELETE - Remove resources

All requests must be made over HTTPS. We do not support HTTP.

Email addresses in request bodies: For contact operations (update, delete), the email address is passed in the JSON request body, not the URL. No URI encoding is needed.

API Endpoints

The Brew API provides the following endpoints:

Automations

Method	Endpoint	Description
POST	`/automations/{automationId}/trigger`	Trigger an automation with a payload
GET	`/automations/{automationId}/trigger`	Get automation trigger info and schema

The {automationId} parameter accepts two formats:

Event ID (recommended): User-defined string like lead_generated, user_signup
Automation ID (legacy): Internal Convex document ID

Transactional Emails

Method	Endpoint	Description
POST	`/send/transactional`	Send a transactional email
GET	`/send/transactional`	Get API documentation

Contacts

Method	Endpoint	Description
POST	`/contacts/import`	Bulk import contacts (up to 10,000 per request)
GET	`/contacts/import`	Get import status or list recent imports
PATCH	`/contacts`	Update a contact by email
DELETE	`/contacts`	Delete a contact or custom fields

Common Use Cases

Transactional Emails
Trigger Automations
Import Contacts
Update Contact
Delete Contact

Send password resets, order confirmations, and other triggered emails:

curl -X POST "https://brew.new/api/send/transactional" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "YOUR_TEMPLATE_ID",
    "to": "user@example.com",
    "variables": {
      "resetLink": "https://app.example.com/reset-password?token=abc123",
      "expiryHours": 24
    }
  }'

Response:

{
  "success": true,
  "data": {
    "sent": 1,
    "failed": 0,
    "results": [
      { "email": "user@example.com", "id": "email_abc123" }
    ]
  },
  "meta": { "requestId": "req_xyz789" }
}

Send to multiple recipients (up to 1,000):

curl -X POST "https://brew.new/api/send/transactional" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "YOUR_TEMPLATE_ID",
    "to": ["user1@example.com", "user2@example.com"],
    "variables": {
      "announcementTitle": "New Feature Released"
    }
  }'

Recipients on suppression lists (bounced, unsubscribed, complained) will be automatically skipped. Check the dropped and droppedRecipients fields in the response.

Trigger a specific automation with a validated payload. Use an Event ID (recommended) or automation document ID:

curl -X POST "https://brew.new/api/automations/order_placed/trigger" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "email": "customer@example.com",
      "firstName": "John",
      "orderId": "ORD-12345",
      "orderTotal": 99.99
    }
  }'

Response:

{
  "success": true,
  "executionId": "exec_abc123",
  "automationId": "kx7777hn1pqfvpq",
  "eventId": "order_placed",
  "status": "running",
  "contact": {
    "email": "customer@example.com",
    "action": "updated"
  }
}

Get automation trigger info and payload schema:

curl "https://brew.new/api/automations/order_placed/trigger" \
  -H "Authorization: Bearer brew_YOUR_API_KEY"

Response:

{
  "automationId": "kx7777hn1pqfvpq",
  "name": "Order Confirmation Flow",
  "status": "active",
  "isPublished": true,
  "eventDefinition": {
    "eventId": "order_placed",
    "eventName": "Order Placed",
    "payloadSchema": {
      "properties": {
        "email": { "type": "string" },
        "firstName": { "type": "string" },
        "orderId": { "type": "string" }
      },
      "required": ["email", "orderId"]
    }
  }
}

The email field is always required in the payload. Brew automatically creates or updates the contact based on this email.

Bulk import contacts (up to 10,000 per request):

curl -X POST "https://brew.new/api/contacts/import" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-batch-123" \
  -d '{
    "contacts": [
      {
        "email": "jane@example.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "subscribed": true,
        "customFields": {
          "companyName": "Acme Corp",
          "planType": "Pro"
        }
      },
      {
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "importId": "imp_abc123",
    "stats": {
      "total": 2,
      "valid": 2,
      "invalid": 0
    }
  },
  "message": "Import queued successfully",
  "meta": { "requestId": "req_xyz789" }
}

Check import status:

curl "https://brew.new/api/contacts/import?importId=imp_abc123" \
  -H "Authorization: Bearer brew_YOUR_API_KEY"

Update an existing contact by email. Custom fields are merged (not replaced):

curl -X PATCH "https://brew.new/api/contacts" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane Marie",
    "lastName": "Smith-Johnson",
    "customFields": {
      "planType": "Enterprise",
      "teamSize": 50
    }
  }'

Response:

{
  "success": true,
  "data": {
    "email": "jane@example.com",
    "firstName": "Jane Marie",
    "lastName": "Smith-Johnson",
    "subscribed": true,
    "customFields": {
      "companyName": "Acme Corp",
      "planType": "Enterprise",
      "teamSize": 50
    }
  },
  "meta": { "requestId": "req_xyz789" }
}

Protected fields (email, createdAt, updatedAt) cannot be updated.

Delete an entire contact or specific custom fields:

# Delete entire contact
curl -X DELETE "https://brew.new/api/contacts" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Response:

{
  "success": true,
  "data": {
    "deleted": true,
    "email": "user@example.com"
  },
  "meta": { "requestId": "req_xyz789" }
}

Delete specific custom fields only:

curl -X DELETE "https://brew.new/api/contacts" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "deleteFields": ["companyName", "planType"]
  }'

Response:

{
  "success": true,
  "data": {
    "deletedFields": ["companyName", "planType"],
    "missingFields": []
  },
  "meta": { "requestId": "req_xyz789" }
}

Standard fields (firstName, lastName, subscribed, tags) cannot be deleted.

Custom Fields

Brew supports custom contact fields to store additional data for segmentation and personalization. Custom fields are passed in the customFields object when importing or updating contacts.

Supported Data Types

Type	Description	Example
`string`	Text values	`"Enterprise"`, `"Product Manager"`
`number`	Numeric values	`50`, `99.99`, `-10`
`boolean`	True/false values	`true`, `false`

Using Custom Fields

Include custom fields when importing or updating contacts:

{
  "email": "user@example.com",
  "firstName": "Jane",
  "customFields": {
    "companyName": "Acme Corp",
    "planType": "Enterprise",
    "teamSize": 50,
    "isTrialing": false
  }
}

Deleting Custom Fields

Use the DELETE endpoint with deleteFields to remove specific custom fields:

curl -X DELETE "https://brew.new/api/contacts" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "deleteFields": ["companyName", "planType"]
  }'

Reserved Field Names

The following field names are reserved and cannot be used as custom fields:

email, firstName, lastName, subscribed, createdAt, updatedAt, tags

Rate Limits

Brew enforces the following rate limits:

Endpoint	Limit
Contact endpoints (`/contacts`, `/contacts/import`)	100 requests per minute
Contact import batch size	10,000 contacts per request
Transactional email recipients	1,000 per request

If you exceed the limit (429 response), implement retries with exponential backoff.

Error Handling

Brew uses standard HTTP status codes with consistent error responses:

Status	Description
200	Success
400	Bad request
401	Invalid API key
404	Resource not found
409	Conflict (duplicate)
429	Rate limit exceeded
500	Server error

Error response format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description of what went wrong",
    "details": { }
  },
  "meta": { "requestId": "req_xxx" }
}

Common error codes include:

INVALID_API_KEY - API key is invalid or expired
PERMISSION_DENIED - API key doesn’t have required permission
INVALID_REQUEST_BODY - Request body is malformed
MISSING_REQUIRED_FIELD - Required field is missing
CONTACT_NOT_FOUND - Contact with specified email not found
RATE_LIMITED - Rate limit exceeded
ALL_RECIPIENTS_BLOCKED - All transactional recipients were suppressed

When you receive errors, we recommend implementing appropriate retry logic with exponential backoff for server errors (5xx) and rate limiting (429).

Common Error Solutions

401 Unauthorized:

Check your API key is correct and active
Ensure you’re using Bearer YOUR_API_KEY format
Generate a new key from Settings → API if needed

400 Bad Request:

Verify all required fields are included
Check data types match the API specification
Ensure email addresses are properly formatted

429 Rate Limited:

Implement exponential backoff in your retry logic
Consider batching requests where possible
Monitor rate limit headers in responses

CORS and Client-Side Issues

Brew’s API does not support cross-origin requests from browsers. Always make API calls from your backend server.

If you see CORS errors, move your API requests to a server-side environment.

Idempotency

Idempotency ensures that operations (like sending emails) are only performed once, even if you make the same API request multiple times. This is particularly useful for:

Preventing duplicate emails when network issues cause retries
Safely retrying failed API calls without worrying about side effects
Maintaining data consistency during system outages or timeouts

For POST requests, include an Idempotency-Key header with a unique value:

curl -X POST "https://brew.new/api/send/transactional" \
  -H "Authorization: Bearer brew_YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "YOUR_TEMPLATE_ID",
    "to": "user@example.com",
    "variables": { "firstName": "John" }
  }'

How Idempotency Works

When you include an idempotency key with a request, Brew checks if it’s seen this key before
If this is the first time seeing the key, Brew processes the request normally
If the key was used in the last 24 hours, Brew returns the same response as the original request without performing the operation again

Best Practices

Use a unique identifier for each distinct operation (UUID is recommended)
Reuse the same key when retrying the exact same request
Keys can be up to 100 characters in length
Consider structuring keys that relate to your business logic (e.g., welcome-email/user-123)
Keys expire after 24 hours, after which they can be reused

If you send a different request body with a previously used idempotency key, you’ll receive an error. Each key must be associated with exactly one set of request parameters.

OpenAPI Specification

Get started quickly with the Brew API using our OpenAPI documents. Import these into API clients like Postman or Insomnia to explore all endpoints with example requests and responses.

Recommended tools: Import our OpenAPI spec into Postman or Insomnia for easy testing and debugging.

Download YAML

OpenAPI 3.1 specification in YAML format

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 analyze documentation with ChatGPT or Claude for deeper insights.

Email Support

Introduction

Automations

Contacts

Transactional

Brew API Overview

Quick Start

Base URL and Authentication

API Endpoints

Automations

Transactional Emails

Contacts

Common Use Cases

Custom Fields

Supported Data Types

Using Custom Fields

Deleting Custom Fields

Reserved Field Names

Rate Limits

Error Handling

Idempotency

How Idempotency Works

Best Practices

OpenAPI Specification

Download YAML

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Introduction

Automations

Contacts

Transactional

​Brew API Overview

​Quick Start

​Base URL and Authentication

​API Endpoints

​Automations

​Transactional Emails

​Contacts

​Common Use Cases

​Custom Fields

​Supported Data Types

​Using Custom Fields

​Deleting Custom Fields

​Reserved Field Names

​Rate Limits

​Error Handling

​Idempotency

​How Idempotency Works

​Best Practices

​OpenAPI Specification

Download YAML

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Brew API Overview

Quick Start

Base URL and Authentication

API Endpoints

Automations

Transactional Emails

Contacts

Common Use Cases

Custom Fields

Supported Data Types

Using Custom Fields

Deleting Custom Fields

Reserved Field Names

Rate Limits

Error Handling

Idempotency

How Idempotency Works

Best Practices

OpenAPI Specification

Need Help?