Grow with us: Join Postmark's new referral partner program and start earning
Learn more
x

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

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, it’s 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

Name and Description are editable. After a Stream is created, it’s 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"
Last updated May 25th, 2021

Still need some help?

Our customer success team has your back!

Contact Support