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:

Authorization: Bearer YOUR_API_KEY

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

​

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.

​

Common Use Cases

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
    }
  }'

{
  "success": true
}

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
    }
  }'

{
  "success": true
}

curl -X POST "https://api.getbrew.ai/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"
    }
  }'

{
  "success": true
}

curl -X POST "https://api.getbrew.ai/v1/contacts/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "subscriptionGroups": {
      "sg_newsletter": true,
      "sg_product_updates": true
    }
  }'

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

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

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

{
  "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.

​

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"
}

​

Error Handling

Brew uses standard HTTP status codes with consistent error responses:

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

​

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.

​

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: