Message Streams

What are Message Streams?

Message streams are channels within an email server that separate different types of emails. This separation is critical for maintaining good deliverability.

Stream Types

Transactional Stream

For emails triggered by user actions that recipients expect and need:

• Welcome emails
• Password resets
• Order confirmations
• Account notifications
• Security alerts

Characteristics:

• High priority delivery
• Expected by recipient
• Usually one-to-one
• Time-sensitive

Broadcast Stream

For marketing and bulk emails sent to multiple recipients:

• Newsletters
• Promotional campaigns
• Product announcements
• Re-engagement emails

Characteristics:

• Sent in bulk
• May be less expected
• Requires explicit consent
• Subject to stricter spam filtering

Why Separate Streams?

Protect Deliverability

Mixing transactional and marketing emails is risky:

1. Marketing emails have higher spam complaint rates
2. Complaints affect your sending reputation
3. A damaged reputation impacts ALL your emails
4. Your critical transactional emails may not reach inboxes

By separating streams, a complaint on a marketing email won't affect your password reset delivery.

Different Sending Patterns

Transactional and marketing emails have different patterns:

Separate Analytics

Track metrics for each stream independently:

• See transactional delivery rates separately from marketing
• Identify issues specific to one email type
• Compare performance across streams

Default Streams

When you create a new server, two streams are created automatically:

1. Transactional - For transactional emails (default)
2. Broadcast - For marketing emails (if enabled)

Using Streams in Code

Specify Stream in API Call

// Send via transactional stream (default)
await client.emails.send({
  from: 'notifications@yourapp.com',
  to: 'user@example.com',
  subject: 'Your order shipped',
  html: orderShippedTemplate,
  stream: 'transactional', // optional, this is the default
});
 
// Send via broadcast stream
await client.emails.send({
  from: 'marketing@yourapp.com',
  to: 'subscriber@example.com',
  subject: 'Our weekly newsletter',
  html: newsletterTemplate,
  stream: 'broadcast',
});

Batch Sending with Stream

await client.emails.sendBatch({
  stream: 'broadcast',
  messages: subscribers.map(sub => ({
    from: 'marketing@yourapp.com',
    to: sub.email,
    subject: 'Special offer just for you',
    html: promoTemplate,
  })),
});

Stream Settings

Each stream has its own configuration:

Tracking Settings

• Track Opens - Insert tracking pixel
• Track Clicks - Rewrite links for tracking

Retry Settings

• Max Retries - How many times to retry failed sends
• Retry Delay - Time between retry attempts

Suppression Settings

• Check Suppressions - Whether to check suppression list before sending

Creating Custom Streams

While most applications only need Transactional and Broadcast, you can create additional streams for specific use cases:

const stream = await client.streams.create({
  serverId: 'srv_123',
  name: 'Digest Emails',
  type: 'broadcast',
});

Best Practices

1. Never mix types - Keep transactional and marketing emails separate
2. Use descriptive names - Make stream purposes clear
3. Monitor separately - Check analytics for each stream
4. Set appropriate tracking - Transactional emails may not need click tracking

Next Steps

• Sender Identities - Set up verified sender addresses
• Best Practices - Improve deliverability
• Tracking - Configure open and click tracking