API Introduction

Brew API Overview

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

Test and verify your API key
Send transactional emails using your published email designs
Trigger automations with events and update contact data
Manage contacts with full CRUD operations
Create custom contact properties for segmentation and personalization
View subscription groups for audience organization

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 Generate Key. Give it a descriptive name like “Production App”. All API requests require authentication using your API key as a Bearer token:

Authorization: Bearer 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://api.brew.new/v1/api-key

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://api.brew.new/v1 All requests must include an Authorization header with your API key:

Authorization: Bearer YOUR_API_KEY

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

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

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

Working with email addresses in URLs: When using email addresses in URL paths (like when deleting or updating contacts), remember to URI-encode them. Replace @ with %40. For example: [email protected] becomes user%40example.com.

API Endpoints

The Brew API provides the following endpoints:

Authentication

Method	Endpoint	Description
GET	`/api-key`	Test and verify your API key

Transactional Emails

Method	Endpoint	Description
POST	`/transactional`	Send a transactional email
GET	`/transactional`	List published transactional email designs

Events

Method	Endpoint	Description
POST	`/events/send`	Send an event to trigger automations

Contacts

Method	Endpoint	Description
POST	`/contacts/create`	Create a new contact
GET	`/contacts/{identifier}`	Find a contact by email or userId
PUT	`/contacts/{identifier}`	Update an existing contact
DELETE	`/contacts/{identifier}`	Delete a contact

Contact Properties

Method	Endpoint	Description
POST	`/contacts/properties`	Create a custom contact property
GET	`/contacts/properties`	List all contact properties

Subscription Groups

Method	Endpoint	Description
GET	`/subscription-groups`	List all subscription groups

Common Use Cases

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

curl -X POST "https://api.brew.new/v1/transactional" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "transactionalId": "te_password_reset",
    "dataVariables": {
      "resetLink": "https://app.example.com/reset-password?token=abc123",
      "expiryHours": 24
    }
  }'

Response:

{
  "success": true
}

You can also add the recipient to your audience while sending:

curl -X POST "https://api.brew.new/v1/transactional" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "transactionalId": "te_welcome",
    "addToAudience": true,
    "firstName": "Sarah",
    "lastName": "Wilson",
    "subscriptionGroups": {
      "sg_newsletter": true
    },
    "dataVariables": {
      "dashboardUrl": "https://app.example.com/dashboard"
    }
  }'

Retrieve your published transactional email designs:

curl "https://api.brew.new/v1/transactional?perPage=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "pagination": {
    "totalResults": 15,
    "returnedResults": 10,
    "perPage": 10,
    "totalPages": 2,
    "nextCursor": "brew_cursor_2024_batch_10"
  },
  "data": [
    {
      "id": "te_welcome_email",
      "name": "Welcome email",
      "lastUpdated": "2024-12-15T10:30:00Z",
      "dataVariables": ["userName", "dashboardUrl"]
    },
    {
      "id": "te_password_reset",
      "name": "Password reset",
      "lastUpdated": "2024-12-22T16:20:00Z",
      "dataVariables": ["resetLink", "validHours"]
    }
  ]
}

Send events to trigger automations and update contact data:

curl -X POST "https://api.brew.new/v1/events/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "eventName": "planUpgrade",
    "eventProperties": {
      "newPlan": "Pro",
      "previousPlan": "Free"
    }
  }'

Response:

{
  "success": true
}

Events can also create/update contacts with additional data:

curl -X POST "https://api.brew.new/v1/events/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "eventName": "userSignup",
    "firstName": "Alex",
    "lastName": "Johnson",
    "userId": "user_12345",
    "eventProperties": {
      "signupSource": "landing_page_a",
      "planSelected": "free"
    },
    "subscriptionGroups": {
      "sg_newsletter": true
    }
  }'

Add contacts to your audience with custom properties:

curl -X POST "https://api.brew.new/v1/contacts/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "userId": "user_12345",
    "subscriptionGroups": {
      "sg_newsletter": true,
      "sg_product_updates": true
    },
    "companyName": "Acme Corp",
    "planType": "Pro"
  }'

Response:

{
  "success": true,
  "id": "cont_2Jk9mN8pQ7rX4vL1"
}

Look up a contact by email or userId:

# Find by email (URI-encoded)
curl "https://api.brew.new/v1/contacts/jane%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Find by userId
curl "https://api.brew.new/v1/contacts/user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "cont_2Jk9mN8pQ7rX4vL1",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Smith",
  "userId": "user_12345",
  "source": "API",
  "subscribed": true,
  "subscriptionGroups": {
    "sg_newsletter": true,
    "sg_product_updates": true
  },
  "companyName": "Acme Corp",
  "planType": "Pro"
}

Update an existing contact’s information:

curl -X PUT "https://api.brew.new/v1/contacts/jane%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane Marie",
    "lastName": "Smith-Johnson",
    "subscriptionGroups": {
      "sg_newsletter": true,
      "sg_promotions": false
    },
    "planType": "Enterprise"
  }'

Response:

{
  "success": true,
  "id": "cont_2Jk9mN8pQ7rX4vL1"
}

For compliance reasons, you can only set subscribed to false (not true).

Remove contacts from your audience:

# Delete by email (note the URI encoding: @ becomes %40)
curl -X DELETE "https://api.brew.new/v1/contacts/user%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete by userId (no encoding needed)
curl -X DELETE "https://api.brew.new/v1/contacts/user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "message": "Contact deleted"
}

Custom Properties

Brew supports custom contact properties to store additional data for segmentation and personalization. Add custom properties as top-level fields in your contact requests.

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`
`date`	Unix timestamps in seconds	`1704067200` (2024-01-01)

Creating Custom Properties

Before using custom properties in API calls, create them first:

curl -X POST "https://api.brew.new/v1/contacts/properties" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "companyName",
    "type": "string"
  }'

Response:

{
  "success": true
}

Listing Properties

# List all properties (built-in + custom)
curl "https://api.brew.new/v1/contacts/properties" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List only custom properties
curl "https://api.brew.new/v1/contacts/properties?list=custom" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reserved Field Names

The following field names are reserved and cannot be used for custom properties:

email, firstName, lastName, userId, source, subscribed, subscriptionGroups

Resetting Properties

Send null as the value to clear any contact property:

{
  "jobTitle": null,
  "teamSize": null
}

Subscription Groups

Subscription groups let you organize your audience and give contacts control over what types of emails they receive. Use the group IDs when creating or updating contacts.

Listing Subscription Groups

curl "https://api.brew.new/v1/subscription-groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  {
    "id": "sg_newsletter",
    "name": "Weekly Newsletter",
    "description": "Our weekly digest of product updates and industry insights"
  },
  {
    "id": "sg_product_updates",
    "name": "Product Updates",
    "description": "Get notified about new features and improvements"
  },
  {
    "id": "sg_promotions",
    "name": "Special Offers",
    "description": null
  }
]

Using Subscription Groups

Include subscription groups when creating or updating contacts:

{
  "email": "[email protected]",
  "subscriptionGroups": {
    "sg_newsletter": true,
    "sg_product_updates": true,
    "sg_promotions": false
  }
}

Rate Limits

Brew enforces 10 requests per second per account.

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,
  "message": "Description of what went wrong"
}

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

Request Body Too Large:

Brew enforces a maximum of 500 characters per value in request bodies
If you receive this error, shorten any long values and try again

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://api.brew.new/v1/transactional" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "transactionalId": "te_welcome"}'

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

Download JSON

OpenAPI 3.1 specification in JSON 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

Contacts

Transactional

Brew API Overview

Quick Start

Base URL and Authentication

API Endpoints

Authentication

Transactional Emails

Events

Contacts

Contact Properties

Subscription Groups

Common Use Cases

Custom Properties

Supported Data Types

Creating Custom Properties

Listing Properties

Reserved Field Names

Resetting Properties

Subscription Groups

Listing Subscription Groups

Using Subscription Groups

Rate Limits

Error Handling

Idempotency

How Idempotency Works

Best Practices

OpenAPI Specification

Download YAML

Download JSON

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Introduction

Contacts

Transactional

​Brew API Overview

​Quick Start

​Base URL and Authentication

​API Endpoints

​Authentication

​Transactional Emails

​Events

​Contacts

​Contact Properties

​Subscription Groups

​Common Use Cases

​Custom Properties

​Supported Data Types

​Creating Custom Properties

​Listing Properties

​Reserved Field Names

​Resetting Properties

​Subscription Groups

​Listing Subscription Groups

​Using Subscription Groups

​Rate Limits

​Error Handling

​Idempotency

​How Idempotency Works

​Best Practices

​OpenAPI Specification

Download YAML

Download JSON

​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

Authentication

Transactional Emails

Events

Contacts

Contact Properties

Subscription Groups

Common Use Cases

Custom Properties

Supported Data Types

Creating Custom Properties

Listing Properties

Reserved Field Names

Resetting Properties

Subscription Groups

Listing Subscription Groups

Using Subscription Groups

Rate Limits

Error Handling

Idempotency

How Idempotency Works

Best Practices

OpenAPI Specification

Need Help?