How to create and send through Message Streams

Adding additional Message Streams in your Postmark account allows you to add new Transactional or Broadcast Message Streams, letting you send all of your application emails through Postmark.

Transactional Message Streams are for messages triggered by a user action, for instance, a password reset or shipping notification. Broadcast Message Streams are messages your application sends to many recipients at once, for instance, a Terms of Service change notification.

Broadcast Message Streams use a separate infrastructure to maintain our high deliverability with Transactional messages. New to Broadcast sending? We've put together some Broadcasts best practices below.

⚠️ Note that there's no way to set a Broadcast Message Stream as your server's default stream. A server's original Transactional Message Stream will always be the default stream for that server, and there is no way to change which stream is the default. As such, in order to send through any other stream other than the server's default stream, you must use one of the methods below to dictate which stream you'd like to send through.

Creating a Message Stream #

1. Choose the Server that you’d like to add a new Message Stream to.
2. Choose Create Message Stream.
3. On the form, fill out the name of the Message Stream and the type of Stream.
4. Then select Create Message Stream which will add the Stream to your Server.

Please Note: You can add up to 10 Message Streams to each Server.

Sending through a Message Stream #

To send with a new Message Stream, Postmark has introduced a Stream ID, which is specified at the time of sending. The Stream ID is found on the top right when viewing a Stream. If no Stream ID is provided when sending, Postmark will send through the default Transactional Stream. 

API #

To send through Postmark’s API, it’s an additional parameter when sending an email with the “MessageStream” parameter. This is the Stream ID. If you're using a Postmark API library, make sure to be on the most recent release of the library for Message Streams support.

Send a Batch email JSON Body:

{
  "From": "sender@example.com",
  "To": "recipient@customer.com",
  "Subject": "Terms of Service Update from Postmark",
  "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 from Postmark",
  "Tag": "tosupdate",
  "HtmlBody": "<strong>Hello</strong>, our Terms of Service are changing...",
  "TextBody": "Hello, our Terms of Service are changing...",
  "MessageStream": "broadcasts"
}

Example Batch email request with cURL:

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

Send with Batch Templates JSON Body:

{
  "From": "sender@example.com",
  "To": "recipient@customer.com",
  "TemplateAlias": "tosupdae",
  "TemplateModel": {
              "customer_name": "John"
  },
  "MessageStream": "broadcasts"
}

Send with Batch Template request with cURL:

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

SMTP #

To send with Broadcast Message Streams via SMTP, there are two options:

1. Include the X-PM-Message-Stream header

This requires the ability to add additional Headers with your SMTP client. The X-PM-Message-Stream header is your Broadcast Message Stream ID.

Server: smtp-broadcasts.postmarkapp.com
Ports: 25, 2525, or 587
Username: username
Password: password
Authentication: Plain text, CRAM-MD5, or TLS
Header: X-PM-Message-Stream: broadcasts

Note: Broadcast Message Streams use a different SMTP URI than Transactional Streams.

2. Authenticate using an SMTP token

An SMTP Token allows you to authenticate SMTP sending through different message streams within Postmark, and can be used in place of the Server API token. To generate an SMTP Token, head to the Stream settings page of the Message Stream you would like to send through, and from there you will be able to generate the Access Key and Secret Key, which are unique to that Stream.

Server: smtp-broadcasts.postmarkapp.com
Ports: 25, 2525, or 587
Username: access key
Password: secret key
Authentication: Plain text, CRAM-MD5, or TLS

Archiving a Message Stream #

Within a Streams settings, the stream can be archived through Archive message stream. Archived streams along with their activity and statistics are automatically deleted 45 days after archiving.

Before a Stream is deleted, it's possible to restore an archived Stream. That's possible by choosing the View archived message stream option when viewing a Server.

The Message Streams API offers a way to programmatically archive and unarchive a Message Stream.

Best Practices for Broadcast Sending #

Okay, so you've created your Broadcast Message Stream and you're ready to go... now what? Be sure to check out our in-depth Best Practices for Bulk Broadcast Sending guide to learn more about Postmark's permission to send policies, steps you can take to help increase your sending reputation when sending bulk, and even some handy tips on the best times to send your bulk messages. If you ensure you check each of the best practices boxes when sending bulk messages through a Postmark Broadcast Message Stream you'll be seeing some amazing deliverability!