​
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:
1

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

Test your connection

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.getbrew.ai/v1/api-key
3

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.getbrew.ai/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.

​
Common Use Cases

Send password resets, order confirmations, and other triggered emails:
curl -X POST "https://api.getbrew.ai/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
}

​
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.
For detailed information about creating and managing custom properties, including supported data types and examples, see our Custom Properties documentation.

​
Rate Limits

Brew enforces 10 requests per second per account. Every response includes rate limit headers:
  • x-ratelimit-limit: Max requests per second
  • x-ratelimit-remaining: Requests left in current window
  • x-ratelimit-reset: When your limit resets (Unix timestamp)
Example response headers: 
{
  "x-ratelimit-limit": "10",
  "x-ratelimit-remaining": "7",
  "x-ratelimit-reset": "1704067260"
}
If you exceed the limit (429 response), implement retries with exponential backoff.

​
Error Handling

Brew uses standard HTTP status codes with consistent error responses:
StatusDescription
200Success
400Bad request
401Invalid API key
404Resource not found
409Conflict (duplicate)
429Rate limit exceeded
500Server error
Error response format: 
{
  "success": false,
  "message": "Description of what went wrong",
  "errorCode": "error_type" // Only included for certain errors
}
When you receive errors, we recommend implementing appropriate retry logic with exponential backoff for server errors (5xx) and rate limiting (429).

​
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.getbrew.ai/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

  1. When you include an idempotency key with a request, Brew checks if it’s seen this key before
  2. If this is the first time seeing the key, Brew processes the request normally
  3. 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:

Search Documentation

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

AI Assistant Chat

Click the sparkle ✨ icon next to the “Ask any question” search bar in the top left to chat with our AI assistant that’s been trained on our entire documentation.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.