Postmark
Postmark API

Send single and batch emails, with or without templates, through a message stream.


Send a single email

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

Sends one email through a message stream on the server identified by the token. Provide HtmlBody, TextBody or both. Maximum message size is 10 MB (including attachments) and 50 recipients across To, Cc and Bcc. If MessageStream is omitted the message is sent through the default outbound transactional stream.

A 200 response means Postmark accepted the message; use the returned MessageID to track delivery, bounces, opens and clicks. Use the token POSTMARK_API_TEST to validate a request without sending.

Send a single email › Request Body

A single email message. Provide at least one of `HtmlBody` or `TextBody`.
From
​string · required

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>
To
​string · required

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com
Cc
​string

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com
Bcc
​string

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Subject
​string · maxLength: 2000

Email subject line. Max 2000 characters.

Example: Password reset
Tag
​string · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset
HtmlBody
​string

HTML body. Required if TextBody is not specified.

Example: <html><body><b>Hello</b> <img src="cid:logo.png"/></body></html>
TextBody
​string

Plain-text body. Required if HtmlBody is not specified.

Example: Hello
ReplyTo
​string

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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 message stream to send through. Defaults to the outbound transactional stream.

Example: outbound
anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = object · requires: HtmlBody
type = object · requires: TextBody
Properties for Variant 1:
HtmlBody
​string · required

HTML body. Required if TextBody is not specified.

Example: <html><body><b>Hello</b> <img src="cid:logo.png"/></body></html>
From
​string

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>
To
​string

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com
Cc
​string

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com
Bcc
​string

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Subject
​string · maxLength: 2000

Email subject line. Max 2000 characters.

Example: Password reset
Tag
​string · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset
TextBody
​string

Plain-text body. Required if HtmlBody is not specified.

Example: Hello
ReplyTo
​string

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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 message stream to send through. Defaults to the outbound transactional stream.

Example: outbound

Send a single email › Responses

The message was accepted.

Result of sending one message. In batch responses, check `ErrorCode` on every entry because the HTTP status is 200 even when individual messages fail.
ErrorCode
​integer · required

0 when the message was accepted; otherwise an API error code.

Example: 0
Message
​string · required

OK on success, or a description of the error.

Example: OK
To
​string

Recipient email address. Field of SendEmailResponse.

Example: receiver@example.com
SubmittedAt
​string · date-time

Time the message was accepted by Postmark.

Example: 2026-10-06T09:15:30.1234567-04:00
MessageID
​string · uuid

Unique ID of the message. Use it to look up details, bounces, opens and clicks.

Example: 0a129aee-e1cd-480d-b08d-4f48548ff48d

Send batch emails

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

Sends up to 500 messages in one call (50 MB total payload, attachments included). Each message is validated and sent independently.

The HTTP status is 200 even if individual messages fail. Inspect ErrorCode on every entry of the response array; results are in the same order as the request.

Send batch emails › Request Body

​SendEmailRequest[] · minItems: 1 · maxItems: 500

Up to 500 messages (and 50 MB total payload, attachments included) per call.

A single email message. Provide at least one of `HtmlBody` or `TextBody`.
From
​string · required

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>
To
​string · required

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com
Cc
​string

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com
Bcc
​string

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Subject
​string · maxLength: 2000

Email subject line. Max 2000 characters.

Example: Password reset
Tag
​string · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset
HtmlBody
​string

HTML body. Required if TextBody is not specified.

Example: <html><body><b>Hello</b> <img src="cid:logo.png"/></body></html>
TextBody
​string

Plain-text body. Required if HtmlBody is not specified.

Example: Hello
ReplyTo
​string

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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 message stream to send through. Defaults to the outbound transactional stream.

Example: outbound
anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = object · requires: HtmlBody
type = object · requires: TextBody
Properties for Variant 1:
HtmlBody
​string · required

HTML body. Required if TextBody is not specified.

Example: <html><body><b>Hello</b> <img src="cid:logo.png"/></body></html>
From
​string

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>
To
​string

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com
Cc
​string

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com
Bcc
​string

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Subject
​string · maxLength: 2000

Email subject line. Max 2000 characters.

Example: Password reset
Tag
​string · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset
TextBody
​string

Plain-text body. Required if HtmlBody is not specified.

Example: Hello
ReplyTo
​string

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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 message stream to send through. Defaults to the outbound transactional stream.

Example: outbound

Send batch emails › Responses

One result per submitted message, in request order. Some entries may contain errors.

One result per submitted message, in the same order as the request.

Result of sending one message. In batch responses, check `ErrorCode` on every entry because the HTTP status is 200 even when individual messages fail.
ErrorCode
​integer · required

0 when the message was accepted; otherwise an API error code.

Example: 0
Message
​string · required

OK on success, or a description of the error.

Example: OK
To
​string

Recipient email address. Field of SendEmailResponse.

Example: receiver@example.com
SubmittedAt
​string · date-time

Time the message was accepted by Postmark.

Example: 2026-10-06T09:15:30.1234567-04:00
MessageID
​string · uuid

Unique ID of the message. Use it to look up details, bounces, opens and clicks.

Example: 0a129aee-e1cd-480d-b08d-4f48548ff48d

Send batch with templates

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

Sends up to 500 templated messages in one call. As with the plain batch endpoint, the HTTP status is 200 even if individual messages fail; check ErrorCode on every entry of the response array.

Send batch with templates › Request Body

Batch of templated emails (max 500 messages and 50 MB per call).
​SendEmailWithTemplateRequest[] · minItems: 1 · maxItems: 500 · required

Up to 500 templated messages.

Example: [{"From":"sender@example.com","To":"receiver@example.com","TemplateAlias":"welcome-email","TemplateModel":{"name":"John Smith","product_name":"Postmark"},"MessageStream":"outbound"}]

Send batch with templates › Responses

One result per submitted message, in request order.

One result per submitted message, in the same order as the request.

Result of sending one message. In batch responses, check `ErrorCode` on every entry because the HTTP status is 200 even when individual messages fail.
ErrorCode
​integer · required

0 when the message was accepted; otherwise an API error code.

Example: 0
Message
​string · required

OK on success, or a description of the error.

Example: OK
To
​string

Recipient email address. Field of SendEmailResponse.

Example: receiver@example.com
SubmittedAt
​string · date-time

Time the message was accepted by Postmark.

Example: 2026-10-06T09:15:30.1234567-04:00
MessageID
​string · uuid

Unique ID of the message. Use it to look up details, bounces, opens and clicks.

Example: 0a129aee-e1cd-480d-b08d-4f48548ff48d

Send email with template

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

Sends one email rendered from a template stored on the server. Identify the template with TemplateId or TemplateAlias and supply the variables in TemplateModel. The template provides the subject and bodies, so do not send Subject, HtmlBody or TextBody.

Send email with template › Request Body

An email rendered from a Postmark template. Provide either `TemplateId` or `TemplateAlias`.
​object · required

Variables used to render the template, as a JSON object. Supports nested objects and arrays.

Example: {"name":"John Smith","product_name":"Postmark","company":{"name":"ACME"}}
From
​SendEmailRequest/properties/From · required

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>
To
​SendEmailRequest/properties/To · required

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com
TemplateId
​integer

ID of the template to use. Provide either TemplateId or TemplateAlias.

Example: 1234567
TemplateAlias
​string

Alias of the template to use. Provide either TemplateAlias or TemplateId.

Example: welcome-email
InlineCss
​boolean

Apply <style> blocks as inline attributes in the rendered HTML. Defaults to true; pass false to opt out.

Example: true

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Tag
​SendEmailRequest/properties/Tag · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message. Field of SendEmailWithTemplateRequest.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB. Field of SendEmailWithTemplateRequest.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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"}

ID of the message stream to send through. Defaults to the outbound transactional stream.

Example: outbound
anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = object · requires: TemplateId
type = object · requires: TemplateAlias
Properties for Variant 1:
TemplateId
​integer · required

ID of the template to use. Provide either TemplateId or TemplateAlias.

Example: 1234567
TemplateAlias
​string

Alias of the template to use. Provide either TemplateAlias or TemplateId.

Example: welcome-email
​object

Variables used to render the template, as a JSON object. Supports nested objects and arrays.

Example: {"name":"John Smith","product_name":"Postmark","company":{"name":"ACME"}}
InlineCss
​boolean

Apply <style> blocks as inline attributes in the rendered HTML. Defaults to true; pass false to opt out.

Example: true

Sender email address. Must belong to a confirmed Sender Signature or verified domain. To include a name use "Full Name <sender@domain.com>". Max 255 characters.

Example: Jane Sender <sender@example.com>

Recipient email addresses, comma separated. Max 50 recipients across To, Cc and Bcc combined.

Example: receiver@example.com

Cc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: copied@example.com

Bcc recipient email addresses, comma separated. Counts toward the 50-recipient limit.

Example: blind-copied@example.com
Tag
​SendEmailRequest/properties/Tag · maxLength: 1000

Tag used to categorize outgoing emails and filter statistics. One tag per message, max 1000 characters.

Example: password-reset

Reply-To override. Defaults to the Reply-To of the Sender Signature. Multiple addresses are comma separated.

Example: reply@example.com
​CustomHeader[]

Custom headers to add to the message. Field of SendEmailWithTemplateRequest.

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

Enable open tracking for this message. Has no effect if open tracking is already enabled on the message stream.

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 to attach. Total message size may not exceed 10 MB. Field of SendEmailWithTemplateRequest.

Example: [{"Name":"report.pdf","Content":"dGVzdCBjb250ZW50","ContentType":"application/pdf","ContentID":"cid:logo.png"}]
​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"}

ID of the message stream to send through. Defaults to the outbound transactional stream.

Example: outbound

Send email with template › Responses

The message was accepted. See sendEmailWithTemplate.

Result of sending one message. In batch responses, check `ErrorCode` on every entry because the HTTP status is 200 even when individual messages fail.
ErrorCode
​integer · required

0 when the message was accepted; otherwise an API error code.

Example: 0
Message
​string · required

OK on success, or a description of the error.

Example: OK
To
​string

Recipient email address. Field of SendEmailResponse.

Example: receiver@example.com
SubmittedAt
​string · date-time

Time the message was accepted by Postmark.

Example: 2026-10-06T09:15:30.1234567-04:00
MessageID
​string · uuid

Unique ID of the message. Use it to look up details, bounces, opens and clicks.

Example: 0a129aee-e1cd-480d-b08d-4f48548ff48d