Message Streams

Streams let you separate your email traffic by purpose. Each server starts with three default streams: Transactional, Broadcast, and Inbound.

Stream Types

Postject supports three stream types, each designed for a specific category of email traffic. Separating your traffic by type is essential for maintaining high deliverability — if a marketing campaign triggers spam complaints, it should never affect the delivery of your transactional emails like password resets and receipts.

Transactional

For messages triggered by a user action — password resets, order confirmations, account notifications, and receipts. These emails are expected by the recipient and typically have the highest engagement rates. Keeping transactional streams separate protects their sender reputation from broadcast-related complaints.

Broadcast

For marketing emails, newsletters, product updates, and promotional content sent to groups of recipients. Broadcast streams have separate reputation tracking, so unsubscribes and complaints from marketing emails do not impact your transactional deliverability.

Inbound

For processing incoming email. Inbound streams receive and parse emails sent to your domain, making them available via the API and webhooks. Useful for support ticket creation, reply tracking, and any workflow that needs to receive email.

Create a Stream

Creates a new message stream within a server. You can create additional streams beyond the three defaults to further segment your email traffic. Requires JWT Bearer authentication.

POSThttps://api.postject.com/v1/streams

Request Body

serverIdstring (required)

The ID of the server to create the stream in.

namestring (required)

A human-readable name for the stream. Must be unique within the server.

typestring (required)

The stream type. One of: transactional, broadcast, or inbound.

json

{
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Alerts",
  "type": "transactional"
}

Response

json

{
  "id": "clx9b4n2c0006wz9z8m9n0o1p",
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "Alerts",
  "slug": "alerts",
  "type": "transactional",
  "description": null,
  "createdAt": "2025-07-16T09:15:00.000Z"
}

List Streams

Returns all message streams for a given server, including the count of messages in each stream. Requires JWT Bearer authentication.

GEThttps://api.postject.com/v1/streams/server/:serverId

json

[
  {
    "id": "clx8f2k9a0002uy7z1a2b3c4d",
    "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
    "name": "Transactional",
    "slug": "transactional",
    "type": "transactional",
    "description": "Password resets, receipts, and account notifications",
    "createdAt": "2025-07-15T10:30:00.000Z",
    "_count": {
      "messages": 1284
    }
  },
  {
    "id": "clx8f2k9a0003uy7z5e6f7g8h",
    "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
    "name": "Broadcast",
    "slug": "broadcast",
    "type": "broadcast",
    "description": "Marketing campaigns and newsletters",
    "createdAt": "2025-07-15T10:30:00.000Z",
    "_count": {
      "messages": 5420
    }
  },
  {
    "id": "clx9b4n2c0006wz9z8m9n0o1p",
    "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
    "name": "Alerts",
    "slug": "alerts",
    "type": "transactional",
    "description": null,
    "createdAt": "2025-07-16T09:15:00.000Z",
    "_count": {
      "messages": 67
    }
  }
]

Update a Stream

Updates the name or description of an existing stream. You cannot change a stream's type after creation. Requires JWT Bearer authentication.

PATCHhttps://api.postject.com/v1/streams/:id

Request Body

namestring (optional)

The new name for the stream.

descriptionstring (optional)

An optional description for the stream.

json

{
  "name": "System Alerts",
  "description": "Critical system notifications and uptime alerts"
}

Response

json

{
  "id": "clx9b4n2c0006wz9z8m9n0o1p",
  "serverId": "clx8f2k9a0001uy7z3g4h5j6k",
  "name": "System Alerts",
  "slug": "system-alerts",
  "type": "transactional",
  "description": "Critical system notifications and uptime alerts",
  "createdAt": "2025-07-16T09:15:00.000Z"
}

Delete a Stream

Permanently deletes a message stream and all messages within it. This action is irreversible. Requires JWT Bearer authentication.

DELETEhttps://api.postject.com/v1/streams/:id

Warning

Deleting a stream permanently removes all messages, events, suppressions, and webhooks associated with it. Default streams (Transactional, Broadcast, Inbound) can also be deleted, but doing so is not recommended.

json

{
  "message": "Stream deleted successfully",
  "id": "clx9b4n2c0006wz9z8m9n0o1p"
}