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, default Streams cannot be deleted, and Servers can only have 1 Inbound Stream.

The ability to add additional Message Streams is currently in a closed beta. Sign up to learn more about Message Streams and get notified when this launches.

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.

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
}

Create a message stream #

post

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

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

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

Example body format

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

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.

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

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.

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.

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
}

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" \
 -X GET \
 -H "Accept: application/json" \
 -H "X-Postmark-Server-Token: server token"

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.

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"
		},
		{
			"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
}

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.

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
}