Postmark
Postmark API

Send one broadcast message to many recipients and track the progress of the request. Requires Bulk API approval from Postmark support.


List bulk API requests

GET
https://api.postmarkapp.com
/email/bulk

Returns the bulk requests submitted on the current server, newest first. Page through results by passing the returned PaginationKey back unchanged as paginationKey. Requires Bulk API approval.

List bulk API requests › query Parameters

count
​integer · min: 1 · max: 500

Number of requests to return per page.

paginationKey
​string

Opaque cursor from the previous response's PaginationKey. Do not decode, modify or construct it; an altered value yields error code 13.

List bulk API requests › Responses

A page of bulk request statuses.

Paged list of bulk request statuses.
​BulkRequestStatus[] · required

Bulk requests submitted on this server, newest first.

Example: [{"Id":"f24af63c-533d-4b7a-ad65-4a7b3202d3a7","SubmittedAt":"2026-10-06T07:25:01.4178645Z","Status":"Accepted","TotalMessages":500,"PercentageCompleted":0,"ReleasedCount":0,"FailedCount":0,"Subject":"October Newsletter"}]
PaginationKey
​string

Opaque cursor for the next page. Pass it back unchanged as paginationKey. Absent on the last page.

Example: eyJTdWJtaXR0ZWRBdCI6IjIwMjYtMDgtMTJUMDk6MDQ6MTdaIn0

Send bulk emails

POST
https://api.postmarkapp.com
/email/bulk

Sends one message to many recipients on a broadcast stream. Define the content (and attachments) once and personalize per recipient with TemplateModel. Postmark releases messages at a rate optimized for deliverability.

Requires approval: the Bulk API must be enabled on your account (contact Postmark support); otherwise the call fails with error code 14.

If any message has a malformed field (for example an invalid address) the whole request is rejected with 422 and nothing is processed. Well-formed but undeliverable messages (suppressed recipients, failed template renders) are accepted and reported through FailedCount.

Send bulk emails › Request Body

Bulk send request: define the content once and personalize with `TemplateModel` per recipient. Total payload may not exceed 50 MB.
From
​string · required

Sender email address. Must belong to a confirmed Sender Signature.

Example: sender@example.com
​BulkMessage[] · minItems: 1 · required

Recipients and their per-message data.

Example: [{"To":"receiver1@example.com","Cc":"cc@example.com","Bcc":"bcc@example.com","TemplateModel":{"FirstName":"Bob"},"Metadata":{"color":"blue","client-id":"12345"},"Headers":[{"Name":"X-Custom-Header","Value":"custom-value"}]}]
ReplyTo
​string

Reply-To override.

Example: replyto@example.com
Subject
​string

Email subject. May contain template variables.

Example: Newsletter for {{FirstName}}
HtmlBody
​string

HTML body. Required if no TextBody or template is given.

Example: <html><body>Hi, {{FirstName}}</body></html>
TextBody
​string

Plain-text body. Required if no HtmlBody or template is given.

Example: Hi, {{FirstName}}
TemplateId
​integer | null

ID of a hosted template. Alternative to submitting content inline.

TemplateAlias
​string | null

Alias of a hosted template. Alternative to submitting content inline.

InlineCss
​boolean

Inline <style> blocks of the template into the HTML. Defaults to true.

Example: true
Tag
​string · maxLength: 1000

Tag used to categorize messages. Max 1000 characters.

Example: Newsletter
​Metadata

Custom key/value metadata attached to a message. Keys and values are strings. Returned in webhook payloads and message details; you can search by a single metadata field at a time.

Example: {"color":"blue","client-id":"12345"}
MessageStream
​string

ID of the broadcast message stream. Defaults to the outbound broadcast stream.

Example: broadcast
TrackOpens
​boolean

Enable open tracking.

Example: true
TrackLinks
​TrackLinks · enum

Link tracking mode. None disables link tracking, HtmlAndText tracks links in both bodies, HtmlOnly tracks only HTML links, TextOnly tracks only plain-text links.

Enum values:
None
HtmlAndText
HtmlOnly
TextOnly
Example: HtmlAndText
​Attachment[]

Files attached to every message.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​CustomHeader[]

Custom headers applied to every message.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]

Send bulk emails › Responses

The request was accepted for processing.

Status of a Bulk API request. The same object is returned when submitting, fetching and listing bulk requests.
Id
​string · uuid · required

ID of the bulk request.

Example: f24af63c-533d-4b7a-ad65-4a7b3202d3a7
Status
​string · enum · required

Processing status of the request.

Enum values:
Accepted
Processing
Completed
Cancelled
Example: Accepted
SubmittedAt
​string · date-time · required

Time Postmark received the request.

Example: 2026-10-06T07:25:01.4178645Z
TotalMessages
​integer · required

Total number of messages in the request.

Example: 500
PercentageCompleted
​number · min: 0 · max: 100 · required

0-100 value showing how much of the request Postmark has finished. 100 means processing finished, not that every message was delivered.

Example: 0
ReleasedCount
​integer · required

Messages handed to the sending pipeline so far. Released is not the same as delivered.

Example: 0
FailedCount
​integer · required

Messages that will not be delivered or retried (for example suppressed recipients or template render failures).

Example: 0
Subject
​string

Email subject. Omitted when the request had none.

Example: October Newsletter

Get bulk request status

GET
https://api.postmarkapp.com
/email/bulk/{bulkRequestId}

Returns the status and progress of a bulk request. Bulk requests are scoped to the server that submitted them; using another server's token returns 404 (error code 12). Requires Bulk API approval.

Get bulk request status › path Parameters

bulkRequestId
​string · uuid · required

ID of the bulk request returned when it was submitted.

Get bulk request status › Responses

The status of the bulk request.

Status of a Bulk API request. The same object is returned when submitting, fetching and listing bulk requests.
Id
​string · uuid · required

ID of the bulk request.

Example: f24af63c-533d-4b7a-ad65-4a7b3202d3a7
Status
​string · enum · required

Processing status of the request.

Enum values:
Accepted
Processing
Completed
Cancelled
Example: Accepted
SubmittedAt
​string · date-time · required

Time Postmark received the request.

Example: 2026-10-06T07:25:01.4178645Z
TotalMessages
​integer · required

Total number of messages in the request.

Example: 500
PercentageCompleted
​number · min: 0 · max: 100 · required

0-100 value showing how much of the request Postmark has finished. 100 means processing finished, not that every message was delivered.

Example: 0
ReleasedCount
​integer · required

Messages handed to the sending pipeline so far. Released is not the same as delivered.

Example: 0
FailedCount
​integer · required

Messages that will not be delivered or retried (for example suppressed recipients or template render failures).

Example: 0
Subject
​string

Email subject. Omitted when the request had none.

Example: October Newsletter