✉️Need a safe space to test your email integrations? Introducing Sandbox Mode.
x

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.

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, it 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: server token
Password: server token
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.

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.

Last updated April 30th, 2021

Still need some help?

Our customer success team has your back!