API Introduction

Brew’s REST API lets you manage contacts, trigger automations, and send transactional emails

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.brew.new/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.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: [e-mail] becomes user%40example.com.

Common Use Cases

Transactional Emails

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": "[e-mail]",
    "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 Contact 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:

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",
  "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).

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": "[e-mail]", "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:

Self-Service Tools

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.