How to create and send through Message Streams

Message Streams let you separate different types of email traffic in Postmark so you can send all of your application email with great deliverability and clear reporting.

Transactional Message Streams are for one-to-one emails triggered by a user action (password resets, receipts, shipping updates).
Broadcast Message Streams are for one-to-many sends (policy updates, product announcements, newsletters). Broadcast traffic uses dedicated infrastructure so transactional delivery stays fast and reliable.

Important: A server’s original Transactional stream is always the default for that server and cannot be changed. If you want to send through any other stream (Transactional or Broadcast), you must explicitly specify that stream when you send (see “Send through a Message Stream” below).

Create a Message Stream

Open the Postmark server where you want to add a stream.
Click Create Message Stream.
Enter a Name and choose a Type (Transactional or Broadcast).
Click Create Message Stream.

Heads-up on limits: See your plan’s limits on how many streams you can create per server: https://postmarkapp.com/pricing

Find your Stream ID

Each stream has a Stream ID you’ll use when sending (for example, broadcasts or outbound). You’ll see it in the top-right of the stream page.

If no Stream ID is provided at send time, Postmark will use the server’s default Transactional stream.

Send through a Message Stream

Email API

Add the MessageStream parameter to each message.

Batch Email (JSON body):

[
  {
    "From": "sender@example.com",
    "To": "recipient@customer.com",
    "Subject": "Terms of Service Update",
    "Tag": "tosupdate",
    "HtmlBody": "<strong>Hello</strong>, our Terms of Service are changing...",
    "TextBody": "Hello, our Terms of Service are changing...",
    "MessageStream": "broadcasts"
  },
  {
    "From": "sender@example.com",
    "To": "another-recipient@customer.com",
    "Subject": "Terms of Service Update",
    "Tag": "tosupdate",
    "HtmlBody": "<strong>Hello</strong>, our Terms of Service are changing...",
    "TextBody": "Hello, our Terms of Service are changing...",
    "MessageStream": "broadcasts"
  }
]

Batch Email (cURL):

curl "https://api.postmarkapp.com/email/batch" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: YOUR_SERVER_TOKEN" \
  -d '[
    {
      "From": "sender@example.com",
      "To": "recipient@customer.com",
      "Subject": "Terms of Service Update",
      "Tag": "tosupdate",
      "HtmlBody": "<strong>Hello</strong>, our Terms of Service are changing...",
      "TextBody": "Hello, our Terms of Service are changing...",
      "MessageStream": "broadcasts"
    },
    {
      "From": "sender@example.com",
      "To": "another-recipient@customer.com",
      "Subject": "Terms of Service Update",
      "Tag": "tosupdate",
      "HtmlBody": "<strong>Hello</strong>, our Terms of Service are changing...",
      "TextBody": "Hello, our Terms of Service are changing...",
      "MessageStream": "broadcasts"
    }
  ]'

Batch with Templates (JSON body):

{
  "Messages": [
    {
      "From": "sender@example.com",
      "To": "recipient@customer.com",
      "TemplateAlias": "tosupdate",
      "TemplateModel": { "customer_name": "John" },
      "MessageStream": "broadcasts"
    },
    {
      "From": "sender@example.com",
      "To": "another-recipient@customer.com",
      "TemplateAlias": "tosupdate",
      "TemplateModel": { "customer_name": "Amy" },
      "MessageStream": "broadcasts"
    }
  ]
}

Batch with Templates (cURL):

curl "https://api.postmarkapp.com/email/batchWithTemplates" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: YOUR_SERVER_TOKEN" \
  -d '{
    "Messages": [
      {
        "From": "sender@example.com",
        "To": "recipient@customer.com",
        "TemplateAlias": "tosupdate",
        "TemplateModel": { "customer_name": "John" },
        "MessageStream": "broadcasts"
      },
      {
        "From": "sender@example.com",
        "To": "another-recipient@customer.com",
        "TemplateAlias": "tosupdate",
        "TemplateModel": { "customer_name": "Amy" },
        "MessageStream": "broadcasts"
      }
    ]
  }'

Using a Postmark library? Update to the latest version to ensure MessageStream is supported: https://postmarkapp.com/developer/integration/official-libraries

SMTP

You have two options for Broadcast sending via SMTP:

Option 1 — Add the stream header (any SMTP client that supports custom headers):

Server: smtp-broadcasts.postmarkapp.com
Ports: 25, 2525, or 587
Auth: PLAIN, CRAM-MD5, or STARTTLS/TLS
Header: X-PM-Message-Stream: broadcasts

Note: Broadcast uses a different SMTP host than Transactional (smtp.postmarkapp.com).

Option 2 — Use an SMTP Token (per-stream credentials):
Generate an Access Key (username) and Secret Key (password) from the stream’s Settings page. These credentials are unique to that stream.

Server: smtp-broadcasts.postmarkapp.com
Ports: 25, 2525, or 587
Username: Access Key
Password: Secret Key
Auth: PLAIN, CRAM-MD5, or STARTTLS/TLS

The Secret Key is only shown once when generated. If it’s lost, create a new SMTP Token.

Archive (or Restore) a Message Stream

In the stream’s Settings, click Archive message stream.
Archived streams (including activity and stats) are automatically deleted after 45 days.
You can restore an archived stream before deletion via View archived message stream on the server page.
You can also archive/unarchive via the API: https://postmarkapp.com/developer/api/message-streams-api

Best Practices for Broadcast Sending

New to Broadcast? Start here:

Keep Transactional and Broadcast on separate streams and subdomains with custom DKIM + Return-Path.
Warm up a new Broadcast stream by sending to your most engaged recipients first, then gradually increase volume.
Follow permission and content best practices to maintain high engagement and deliverability.

Deep-dive guide: https://postmarkapp.com/developer/user-guide/bulk-email/best-practices-for-bulk-broadcast-sending