Skip to main content

​
Overview

The Transactional resource allows you to send transactional emails using your published Brew templates. Access it via client.send.transactional.
SDK Parameter Names: The SDK uses chatId for template IDs and variables for template data. The REST API uses different names (transactionalId and dataVariables). This documentation covers the SDK interface.

​
Methods

MethodDescription
send.transactional.send()Send a transactional email
send.transactional.documentation()Get API documentation info

​
Send Transactional Email

Send a transactional email using a published email template.
The template must be published (status: “live”) in Brew before it can be used via API.

​
Basic Usage

import BrewSDK from 'brew-sdk';

const client = new BrewSDK();

const response = await client.send.transactional.send({
  chatId: 'your-template-id',
  to: '[email protected]',
  variables: {
    firstName: 'John',
    orderNumber: 'ORD-12345',
  },
});

console.log('Emails sent:', response.data.sent);

​
Send to Multiple Recipients

Send the same email to multiple recipients (up to 1000): 
const response = await client.send.transactional.send({
  chatId: 'announcement-template',
  to: [
    '[email protected]',
    '[email protected]',
    '[email protected]',
  ],
  variables: {
    announcement: 'New feature launched!',
    ctaUrl: 'https://example.com/new-feature',
  },
});

console.log(`Sent: ${response.data.sent}, Failed: ${response.data.failed}`);

​
Override Sender and Subject

const response = await client.send.transactional.send({
  chatId: 'order-confirmation',
  to: '[email protected]',
  from: '[email protected]',
  replyTo: '[email protected]',
  subject: 'Your Order #12345 is Confirmed!',
  variables: {
    orderNumber: '12345',
    orderTotal: '$99.99',
    deliveryDate: 'January 25, 2024',
  },
});

​
With Request Options

You can pass additional options like custom timeouts or retries: 
const response = await client.send.transactional.send(
  {
    chatId: 'urgent-notification',
    to: '[email protected]',
    variables: { message: 'Important update' },
  },
  {
    timeout: 10000,    // 10 second timeout
    maxRetries: 5,     // Retry up to 5 times
  }
);

​
Parameters

​
chatId
string
required
The transactional email template ID from Brew.
​
to
string | string[]
required
Recipient email address(es). Can be a single email or an array of up to 1000 emails.
​
variables
object
Template variables as key-value pairs. These populate dynamic content in your email template.
​
from
string
Override the default sender email address.
​
replyTo
string
Set the reply-to email address.
​
subject
string
Override the default subject line.

​
Response

interface TransactionalSendResponse {
  success: true;
  data: {
    sent?: number;           // Number of emails sent successfully
    failed?: number;         // Number of emails that failed
    results?: Array<{
      email?: string;
      id?: string;           // Email ID (if successful)
      error?: string;        // Error message (if failed)
    }>;
  };
  meta?: {
    requestId?: string;
  };
}

​
Get API Documentation

Retrieve API documentation and endpoint information: 
const docs = await client.send.transactional.documentation();

console.log('API Version:', docs.version);
console.log('Documentation:', docs.documentation);

docs.endpoints?.forEach(endpoint => {
  console.log(`${endpoint.methods?.join(', ')} ${endpoint.path}`);
  console.log(`  ${endpoint.description}`);
});

​
Response

interface TransactionalDocumentationResponse {
  version?: string;               // API version
  documentation?: string;         // Link to full docs
  endpoints?: Array<{
    path?: string;
    methods?: string[];
    description?: string;
  }>;
}

​
Common Use Cases

​
Password Reset Email

const response = await client.send.transactional.send({
  chatId: 'password-reset-template',
  to: user.email,
  variables: {
    userName: user.firstName,
    resetLink: `https://app.example.com/reset?token=${token}`,
    expiryHours: 24,
  },
});

​
Order Confirmation

const response = await client.send.transactional.send({
  chatId: 'order-confirmation-template',
  to: order.customerEmail,
  subject: `Order Confirmed - #${order.id}`,
  variables: {
    orderNumber: order.id,
    orderTotal: formatCurrency(order.total),
    items: order.items.map(item => ({
      name: item.name,
      quantity: item.quantity,
      price: formatCurrency(item.price),
    })),
    shippingAddress: order.shippingAddress,
    estimatedDelivery: order.estimatedDelivery,
  },
});

​
Welcome Email

const response = await client.send.transactional.send({
  chatId: 'welcome-email-template',
  to: newUser.email,
  variables: {
    firstName: newUser.firstName,
    dashboardUrl: 'https://app.example.com/dashboard',
    helpCenterUrl: 'https://help.example.com',
    trialDays: 14,
  },
});

​
Team Invitation

const response = await client.send.transactional.send({
  chatId: 'team-invitation-template',
  to: invitee.email,
  replyTo: inviter.email,
  variables: {
    inviterName: inviter.name,
    teamName: team.name,
    inviteLink: `https://app.example.com/invite/${inviteToken}`,
    expiryDays: 7,
  },
});

​
Handling Results

​
Check Individual Results

When sending to multiple recipients, check each result: 
const response = await client.send.transactional.send({
  chatId: 'newsletter-template',
  to: ['[email protected]', '[email protected]', 'invalid-email'],
  variables: { /* ... */ },
});

// Log successful sends
response.data.results?.forEach(result => {
  if (result.id) {
    console.log(`Sent to ${result.email}: ID ${result.id}`);
  } else {
    console.error(`Failed for ${result.email}: ${result.error}`);
  }
});

// Summary
console.log(`Total: ${response.data.sent} sent, ${response.data.failed} failed`);

​
Type Definitions

Import types for better TypeScript support: 
import BrewSDK from 'brew-sdk';

// Parameter types
type TransactionalSendParams = BrewSDK.Send.TransactionalSendParams;

// Response types
type TransactionalSendResponse = BrewSDK.Send.TransactionalSendResponse;
type TransactionalDocumentationResponse = BrewSDK.Send.TransactionalDocumentationResponse;

// Example with typed params
const params: TransactionalSendParams = {
  chatId: 'template-id',
  to: '[email protected]',
  variables: {
    name: 'John',
  },
};

const response: TransactionalSendResponse = 
  await client.send.transactional.send(params);

​
Error Handling

import BrewSDK from 'brew-sdk';

const client = new BrewSDK();

try {
  await client.send.transactional.send({
    chatId: 'invalid-template-id',
    to: '[email protected]',
  });
} catch (error) {
  if (error instanceof BrewSDK.NotFoundError) {
    console.error('Template not found or not published');
  } else if (error instanceof BrewSDK.BadRequestError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof BrewSDK.RateLimitError) {
    console.error('Rate limited - try again later');
  } else {
    throw error;
  }
}

​
Best Practices

Name your templates descriptively in Brew so the IDs are easy to identify:
  • welcome-email
  • password-reset
  • order-confirmation
Ensure all required template variables are present:
function sendOrderConfirmation(order: Order) {
  if (!order.id || !order.customerEmail || !order.total) {
    throw new Error('Missing required order data');
  }
  
  return client.send.transactional.send({
    chatId: 'order-confirmation',
    to: order.customerEmail,
    variables: {
      orderNumber: order.id,
      orderTotal: order.total,
    },
  });
}
Always check results and handle failures:
const response = await client.send.transactional.send(params);

if (response.data.failed && response.data.failed > 0) {
  // Log failures for investigation
  const failures = response.data.results?.filter(r => r.error);
  console.error('Email failures:', failures);
}
Set a reply-to address so customer replies go to the right place:
await client.send.transactional.send({
  chatId: 'support-response',
  to: customer.email,
  replyTo: '[email protected]',
  // ...
});

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

ChatGPT/Claude Integration

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