Overview

Integration

User guide

API reference

Webhooks

Message Streams API

Lets you manage message streams for a specific server. Please note: A Server may have up to 10 Streams, including the default ones. Default Streams cannot be deleted, and Servers can only have 1 Inbound Stream.

List message streams #

get

/message-streams

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/message-streams?MessageStreamType=all&IncludeArchivedStreams=true" \
 -X GET \
 -H "Accept: application/json" \
 -H "X-Postmark-Server-Token: server token"

Querystring parameters

MessageStreamType

Filters message streams based on stream type. Possible options: All Inbound Transactional Broadcasts. Defaults to All.
IncludeArchivedStreams

Boolean filter for including archived message streams in list. Defaults to False.

Response

MessageStreams array

List of message streams in a server.
ID string

ID of message stream.
ServerID integer

ID of server the message stream is associated with.
Name string

Name of message stream.
Description string

Description of message stream. This value can be null.
MessageStreamType string

Type of message stream. Possible options: Inbound Broadcasts Transactional
CreatedAt string

Timestamp of date message stream was created.
UpdatedAt string

Timestamp of date message stream was last updated. This value can be null.
ArchivedAt string

Timestamp of date message stream was archived. This value can be null.
ExpectedPurgeDate string

Archived streams are deleted 45 days after archiving date. Until this date, it can be restored. This value is null if the stream is not archived.
SubscriptionManagementConfiguration object

Subscription management options for the Stream.
UnsubscribeHandlingType

The unsubscribe management option used for the Stream. Broadcast Message Streams require unsubscribe management, Postmark is default. For Inbound and Transactional Streams default is none. Possible options: None (transactional/inbound streams) Custom Postmark.
TotalCount integer

Number of message streams retrieved

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
	"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",
			"ExpectedPurgeDate": "2020-08-17T00:00:00-04:00",
			"SubscriptionManagementConfiguration": {
				"UnsubscribeHandlingType": "Postmark"
			}
		},
		{
			"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,
			"ExpectedPurgeDate": null,
			"SubscriptionManagementConfiguration": {
				"UnsubscribeHandlingType": "none"
			}
		},
		{
			"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,
			"ExpectedPurgeDate": null,
			"SubscriptionManagementConfiguration": {
				"UnsubscribeHandlingType": "none"
			}
		},
		{
			"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,
			"ExpectedPurgeDate": null,
			"SubscriptionManagementConfiguration": {
				"UnsubscribeHandlingType": "none"
			}
		}
	],
	"TotalCount": 4
}

Get a message stream #

get

/message-streams/{stream_ID}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

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"

Response

ID string

ID of message stream.
ServerID integer

ID of server the message stream is associated with.
Name string

Name of message stream.
Description string

Description of message stream. This value can be null.
MessageStreamType string

Type of message stream. Possible options: Inbound Broadcasts Transactional
CreatedAt string

Timestamp of date message stream was created.
UpdatedAt string

Timestamp of date message stream was last updated. This value can be null.
ArchivedAt string

Timestamp of date message stream was archived. This value can be null.
ExpectedPurgeDate string

Archived streams are deleted 45 days after archiving date. Until this date, it can be restored. This value is null if the stream is not archived.
SubscriptionManagementConfiguration object

Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option used for the Stream. Broadcast Message Streams require unsubscribe management, Postmark is default. For Inbound and Transactional Streams default is none. Possible options: None (transactional/inbound streams) Custom Postmark.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
	"ID": "broadcasts",
	"ServerID": 123456,
	"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": null,
	"ExpectedPurgeDate": null,
	"SubscriptionManagementConfiguration": {
		"UnsubscribeHandlingType": "Postmark"
	}
}

Edit a message stream #

patch

/message-streams/{stream_ID}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

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"
}'

Body format

Name string

Name of message stream.
Description string

Description of message stream.
SubscriptionManagementConfiguration object

Optional. Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option for the stream. For transactional streams default is None. For broadcast streams default is Postmark. Unsubscribe management is required for broadcast message streams, approved accounts can use Custom. Possible options: none Postmark Custom.

Example body format

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

Response

ID string

ID of message stream.
ServerID integer

ID of server the message stream is associated with.
Name string

Name of message stream.
Description string

Description of message stream. This value can be null.
MessageStreamType string

Type of message stream. Possible options: Inbound Broadcasts Transactional
CreatedAt string

Timestamp of date message stream was created.
UpdatedAt string

Timestamp of date message stream was last updated.
ArchivedAt string

Timestamp of date message stream was archived. This value can be null.
ExpectedPurgeDate string

Archived streams are deleted 45 days after archiving date. Until this date, it can be restored. This value is null if the stream is not archived.
SubscriptionManagementConfiguration object

Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option used for the Stream. Broadcast Message Streams require unsubscribe management, Postmark is default. For Inbound and Transactional Streams default is none. Possible options: None (transactional\inbound streams) Custom Postmark.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
	"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-03T00:00:00-04:00",
	"ArchivedAt": null,
	"ExpectedPurgeDate": null,
	"SubscriptionManagementConfiguration": {
		"UnsubscribeHandlingType": "none"
	}
}

Create a message stream #

post

/message-streams

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/message-streams" \
 -X POST \
 -H "Accept: application/json" \
 -H "Content-Type: 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"
}'

Body format

ID string required

The ID of the message stream being created. This is used when sending messages to specify the sending message stream.
Name string required

The name of the message stream.
Description string

A description of the message stream.
MessageStreamType string required

The type of message stream being created. Possible options Broadcasts Transasctional
SubscriptionManagementConfiguration object

Optional. Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option for the stream. For transactional streams default is None. For broadcast streams default is Postmark. Unsubscribe management is required for broadcast message streams, approved accounts can use Custom. Possible options: none Postmark Custom.

Example body format

{
	"ID": "transactional-dev",
	"Name": "My Dev Transactional Stream",
	"Description": "This is my second transactional stream",
	"MessageStreamType": "Transactional",
	"SubscriptionManagementConfiguration": {
		"UnsubscribeHandlingType": "None"
	}
}

Response

ID string

ID of message stream.
ServerID integer

ID of server the message stream is associated with.
Name string

Name of message stream.
Description string

Description of message stream. This value can be null.
MessageStreamType string

Type of message stream. Possible options: Broadcasts Transactional
CreatedAt string

Timestamp of date message stream was created.
UpdatedAt string

Timestamp of date message stream was last updated. This value can be null.
ArchivedAt string

Timestamp of date message stream was archived. This value can be null.
SubscriptionManagementConfiguration object

Optional. Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option used for the Stream. Broadcast Message Streams require unsubscribe management, Postmark is default. For Inbound and Transactional Streams default is none. Possible options: None (transactional\inbound streams) Custom Postmark.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
	"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-02T00:00:00-04:00",
	"ArchivedAt": "2020-07-02T00:00:00-04:00",
	"SubscriptionManagementConfiguration": {
		"UnsubscribeHandlingType": "None"
	}
}

Archive a message stream #

post

/message-streams/{stream_ID}/archive

Request headers

Content-Length required

Set to 0
Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

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"

Response

ID string

ID of message stream.
ServerID string

ID of server the message stream is associated with.
ExpectedPurgeDate string

Stream is deleted 45 days after archiving date. Until this date, it can be restored.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

Unarchive a message stream #

post

/message-streams/{stream_ID}/unarchive

Request headers

Content-Length required

Set to 0
Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

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"

Response

ID string

ID of message stream.
ServerID string

ID of server the message stream is associated with.
Name string

Name of message stream.
Description string

Description of message stream. This value can be null.
MessageStreamType string

Type of message stream. Possible options: Inbound Broadcasts Transactional
CreatedAt string

Timestamp of date message stream was created.
UpdatedAt string

Timestamp of date message stream was last updated. This value can be null.
ArchivedAt string

This value will be null.
SubscriptionManagementConfiguration object

Subscription management options for the Stream.
UnsubscribeHandlingType string

The unsubscribe management option used for the Stream. Broadcast Message Streams require unsubscribe management, Postmark is default. For Inbound and Transactional Streams default is none. Possible options: None (transactional/inbound streams) Custom Postmark.

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",
	"ArchivedAt": null,
	"SubscriptionManagementConfiguration": {
		"UnsubscribeHandlingType": "none"
	}
}