Managing Message Streams with Postmark's API

Adding additional Message Streams in your Postmark account allows you to add new Transactional or Broadcast Message Streams, letting you to 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.

Postmark’s API has a /message-streams endpoint allowing management of a Server’s Message Streams.

Jump to an endpoint:

• Get a Message Stream
• Create a Message Stream
• Edit a Message Stream
• List a Message Stream
• Archive a Message Stream
• Unarchive a Message Stream

Get a Message Stream

Method: GET
Endpoint: https://api.postmarkapp.com/message-streams/{stream_ID}
Example Body: No body is needed for this API call

Example Response:

{
  ID: broadcasts,
  ServerID: 123456,
  Name: Broadcast Stream,
  Description: This is my stream to send broadcast messages, //can be null
  MessageStreamType: Broadcasts,
  CreatedAt: 2020-07-01T00:00:00-04:00,
  UpdatedAt: 2020-07-01T00:00:00-04:00, //can be null
  ArchivedAt: 2020-07-01T00:00:00-04:00 //can be null
}

Example request with curl:

curl https://api.postmarkapp.com/message-streams/{stream_ID} \
  -X GET \
  -H Accept: application/json \
  -H X-Postmark-Server-Token: server token

Create a Message Stream

After a Stream is created, its Stream type and ID cannot be changed.

Method: POST
Endpoint: https://api.postmarkapp.com/message-streams/
Example Body:

{
  ID: transactional-dev, //required
  Name: My Dev Transactional Stream, //required
  Description: This is my second transactional stream, //optional
  MessageStreamType: Transactional //required
}

Example Response:

{
  ID: transactional-dev,
  ServerID: 123457,
  Name: My Dev Transactional Stream,
  Description: This is my second transactional stream, //can be null
  MessageStreamType: Transactional,
  CreatedAt: 2020-07-02T00:00:00-04:00,
  UpdatedAt: 2020-07-02T00:00:00-04:00, //can be null
  ArchivedAt: 2020-07-02T00:00:00-04:00 //can be null
}

Example request with curl:

curl https://api.postmarkapp.com/message-streams \
  -X POST \
  -H Accept: application/json \
  -H X-Postmark-Server-Token: server token\
  -d {'ID': 'transactional-dev', 'Name': 'My Dev Transactional Stream', 'Description':'This is my second transactional stream', 'MessageStreamType':'Transactional'}

Edit a Message Stream

The name and Description are editable. After a Stream is created, its Stream type and ID cannot be changed.

Method: PATCH
Endpoint: https://api.postmarkapp.com/message-streams/{stream_ID}
Example Body:

{
  Name: Updated Dev Stream, //optional
  Description: Updating my dev transactional stream //optional
}

Example Response:

{
  ID: transactional-dev,
  ServerID: 123457,
  Name: Updated Dev Stream,
  Description: Updating my dev transactional stream, //can be null
  MessageStreamType: Transactional,
  CreatedAt: 2020-07-02T00:00:00-04:00,
  UpdatedAt: 2020-07-03T00:00:00-04:00, //can be null
  ArchivedAt: 2020-07-02T00:00:00-04:00 //can be null
}

Example request with curl:

curl -L -X PATCH https://api.postmarkapp.com/message-streams/{stream_ID} \
  -H Content-Type: application/json \
  -H X-Postmark-Server-Token: server token \
  -d {'Name': 'Updated Dev Stream', 'Description':'Updating my dev transactional stream'}

List Message Streams

Method: GET
Endpoint: https://api.postmarkapp.com/message-streams
Example Body:

Example Response:

{
	MessageStreams: [{
			ID: broadcasts,
			ServerID: 123457,
			Name: Broadcast Stream,
			Description: This is my stream to send broadcast messages,
			MessageStreamType: Broadcasts,
			CreatedAt: 2020-07-01T00:00:00-04:00,
			UpdatedAt: 2020-07-01T00:00:00-04:00,
			ArchivedAt: 2020-07-03T00:00:00-04:00
		},
		{
			ID: outbound,
			ServerID: 123457,
			Name: Transactional Stream,
			Description: This is my stream to send transactional messages,
			MessageStreamType: Transactional,
			CreatedAt: 2020-07-01T00:00:00-04:00,
			UpdatedAt: 2020-07-05T00:00:00-04:00,
			ArchivedAt: null
		},
		{
			ID: inbound,
			ServerID: 123457,
			Name: Inbound Stream,
			Description: Stream used for receiving inbound messages,
			MessageStreamType: Inbound,
			CreatedAt: 2020-07-01T00:00:00-04:00,
			UpdatedAt: null,
			ArchivedAt: null
		},
		{
			ID: transactional-dev,
			ServerID: 123457,
			Name: My Dev Transactional Stream,
			Description: This is my second transactional stream,
			MessageStreamType: Transactional,
			CreatedAt: 2020-07-02T00:00:00-04:00,
			UpdatedAt: 2020-07-04T00:00:00-04:00,
			ArchivedAt: null
		}
	],
	TotalCount: 4
}

Example request with curl:

curl https://api.postmarkapp.com/message-streams \
  -X GET \
  -H Accept: application/json \
  -H X-Postmark-Server-Token: server token

Archive a Message Stream

When a stream is archived, it's available to unarchive for 45 days. The Stream will not be visible in Postmark's UI. After 45 days, it's deleted — This is the expected purge date.

Method: POST
Endpoint: https://api.postmarkapp.com/message-streams/{stream_ID}/archive
Example Body: No body is needed for this API call

Example Response:

{
	ID: transactional-dev,
	ServerID: 123457,
	ExpectedPurgeDate: 2020-08-30T12:30:00.00-04:00
}

Example request with curl:

curl https://api.postmarkapp.com/message-streams/{stream_ID}/archive \
 -X POST \
 -H Content-Length: 0 \
 -H Accept: application/json \
 -H X-Postmark-Server-Token: server token

Unarchive a Message Stream

When a stream is unarchived, it will re-appear in Postmark's UI. Unarchiving is available up to 45 days after a Stream is archived.

Method: POST
Endpoint: https://api.postmarkapp.com/message-streams/{stream_ID}/unarchive
Example Body: No body is needed for this API call

Example Response:

{
	ID: transactional-dev,
	ServerID: 123457,
	Name: Updated Dev Stream,
	Description: Updating my dev transactional stream,
	MessageStreamType: Transactional,
	CreatedAt: 2020-07-02T00:00:00-04:00,
	UpdatedAt: 2020-07-04T00:00:00-04:00, //can be null
	ArchivedAt: null
}

Example request with curl:

curl https://api.postmarkapp.com/message-streams/{stream_ID}/unarchive \
 -X POST \
 -H Content-Length: 0 \
 -H Accept: application/json \
 -H X-Postmark-Server-Token: server token