Skip to main content
POST
/
transactional
curl --request POST \
  --url https://api.brew.new/v1/transactional \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "user@example.com",
  "transactionalId": "te_password_reset",
  "addToAudience": false,
  "dataVariables": {
    "resetLink": "https://app.example.com/reset-password?token=abc123",
    "expiryHours": 24,
    "userName": "John"
  }
}'
{
  "success": true
}

Authorizations

​
Authorization
string
header
required

Include your Brew API key as a Bearer token in the Authorization header.

Example: Authorization: Bearer bw_api_your_key_here

Headers

​
Idempotency-Key
string

Unique identifier to prevent duplicate emails. Use this to safely retry requests without sending duplicate emails. We recommend using UUIDs or another method with sufficient entropy to avoid collisions. Keys expire after 24 hours and should be up to 100 characters.

Maximum length: 100

Body

application/json

Specify the recipient, email design to use, and any dynamic data. Optionally add the contact to your audience with basic contact information like names and subscription groups.

Contact Matching (when addToAudience is true): You can provide email, userId, or both to identify the contact. When both are provided, Brew searches for a contact matching either identifier. If a contact is found (for example, by email), the other identifier (userId) will be updated on that contact. If no existing contact matches either identifier, a new contact is created with both values.

Request body for sending a transactional email

​
email
string<email>
required

Recipient's email address

Example:

"customer@example.com"

​
transactionalId
string
required

ID of the transactional email to send (from your published designs)

Example:

"te_password_reset"

​
addToAudience
boolean
default:false

Whether to create a contact in your audience if one doesn't exist

​
firstName
string

Contact's first name (used when addToAudience is true)

Example:

"John"

​
lastName
string

Contact's last name (used when addToAudience is true)

Example:

"Smith"

​
userId
string

Unique external user ID (used when addToAudience is true)

Example:

"user_12345"

​
source
string

Custom source value (used when addToAudience is true, defaults to "API")

Example:

"Password reset"

​
subscribed
boolean
default:true

Whether the contact is subscribed to marketing emails (used when addToAudience is true)

​
subscriptionGroups
object

Subscription groups to add the contact to (used when addToAudience is true)

Example:
{
  "sg_newsletter": true,
  "sg_product_updates": false
}
​
dataVariables
object

Variables to populate in the email template (must match the email's defined variables). Supports strings, numbers, and booleans. Boolean values enable conditional content in templates.

Supported Types:

  • string - Text values for names, URLs, messages
  • number - Numeric values for amounts, counts, percentages
  • boolean - True/false values for conditional content (e.g., show/hide sections)
Example:
{
  "resetLink": "https://app.example.com/reset?token=abc123",
  "expiryHours": 24,
  "showUpgradePrompt": true
}
​
attachments
object[]

File attachments to include with the email. Maximum 10MB total across all files. This feature requires enablement - please contact founders@brew.new to activate attachments for your account.

Response

Email sent successfully

Success response for transactional email sending

​
success
boolean
required

Indicates the email was sent successfully

Example:

true

⌘I