Overview

Integration

User guide

API reference

Webhooks

Bulk Email

Send bulk emails #

⚠️ Work in progress: This endpoint is available to early access customers only. ⚠️

Here's a preview of our brand new Bulk API endpoint that will make it a whole lot easier for senders (like you!) to send Broadcast email at scale. At this point, the endpoint is available for early access customers only. If you'd like to join the early access program (or just be notified as soon as the Bulk API is available to everyone), you can let us know here.  

If you’re looking to send the same message to multiple recipients with a single API call—for example to send newsletters, marketing announcements, or similar—our Bulk endpoint makes that easy: 

  • You define the message content (and attachments, if you’d like to send any) only once, and then use template variables to customize the message for each recipient, if needed.
  • You can add as many recipients as you need per API call, as long as you stay within the 50 MB payload size limit, including attachments.
  • Postmark will optimize the sending speed for you. If you’re sending a large amount of emails at once, we’ll release them at the appropriate rate for best deliverability results.
post

/email/bulk

Request headers

Content-Type required

application/json

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/email/bulk" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
    "From": "sender@example.com",
    "Subject": "This is a bulk email for {{FirstName}}",
    "TextBody": "Hi, {{FirstName}}",
    "HtmlBody": "<html><body>Hi, {{FirstName}}</body></html>",
    "MessageStream": "broadcast",
    "Messages": [
      {
        "To": "receiver1@example.com",
        "TemplateModel": {
          "FirstName": "Bob"
        }
      },
      {
        "To": "receiver2@example.com",
        "Cc": "cc@example.com",
        "TemplateModel": {
          "FirstName": "Frieda"
        }
      },
      {
        "To": "receiver3@example.com",
        "Bcc": "bcc@example.com",
        "TemplateModel": {
          "FirstName": "Elijah"
        }
      }
    ]
  }'

Body format

From string required

The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name sender@domain.com". Punctuation in the name would need to be escaped.

ReplyTo string

Reply To override email address. Defaults to the Reply-To set in the sender signature.

Subject string

Email subject

HtmlBody string

If no TextBody specified, HTML email message

TextBody string

If no HtmlBody specified Plain text email message

TemplateId integer

If you’re looking to host your template in Postmark rather than submitting the HTML in your API call, use the TemplateID or the TemplateAlias (below) to specify the template to use when sending this message.

TemplateAlias string

If you’re looking to host your template in Postmark rather than submitting the HTML in your API call, use the TemplateAlias or TemplateID (above) to specify the template to use when sending this message.

InlineCss boolean

By default, if the specified template contains an HTMLBody, we will apply the style blocks as inline attributes to the rendered HTML content. You may opt-out of this behavior by passing false for this request field.

Tag string

Email tag that allows you to categorize outgoing emails and get detailed statistics. Max characters 1000.

Metadata object

Custom metadata key/value pairs. If metadata objects are present on the message level, they’ll take precedence over those on the request level.

MessageStream string

Set the message stream ID that's used for sending. If not provided, message will default to the outbound broadcast stream.

TrackOpens boolean

Activate open tracking for this email.

TrackLinks string

Activate link tracking for links in the HTML or Text bodies of this email. Possible options: None HtmlAndText HtmlOnly TextOnly

Attachments array

List of attachments

Headers array

List of custom headers to include. If header objects are present on the message level, they’ll take precedence over those on the request level.

Messages an array of Message objects required

List of recipients you’re looking to send the email to, including any data related to each individual message.

Message - To string

Recipient email address. Multiple addresses are comma-separated. Max 50.

Message - Cc string

Cc recipient email address. Multiple addresses are comma-separated. Max 50.

Message - Bcc string

Bcc recipient email address. Multiple addresses are comma-separated. Max 50.

Message - TemplateModel object

List of template variables to customize each message with recipient-specific content.

Message - Metadata object

Custom metadata key/value pairs. If metadata objects are present on the message level, they’ll take precedence over those on the request level.

Message - Headers array

List of custom headers to include. If header objects are present on the message level, they’ll take precedence over those on the request level.

Example body format

{
  "From": "sender@example.com",
  "ReplyTo": "replyto@example.com",
  "Subject": "This is a bulk email for {{FirstName}}",
  "HtmlBody": "<html><body>Hi, {{FirstName}}</body></html>",
  "TextBody": "Hi, {{FirstName}}",
  "TemplateId": null,
  "TemplateAlias": null,
  "Metadata": {
    "color": "blue",
    "client-id": "12345"
  },
  "MessageStream": "broadcast",
  "TrackOpens": true,
  "TrackLinks": "None",
  "Attachments": [
    {
      "Name": "readme.txt",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "text/plain"
    }
  ],
  "Headers": [
    {
      "Name": "CUSTOM-HEADER",
      "Value": "value"
    }
  ],
  "InlineCss": true,
  "Tag": "Newsletter",
  "Messages": [
    {
      "To": "receiver1@example.com",
      "TemplateModel": {
        "FirstName": "Bob"
      },
      "Metadata": {
        "color": "blue",
        "client-id": "12345"
      },
      "Headers": [
        {
          "Name": "CUSTOM-HEADER",
          "Value": "value"
        }
      ]
    },
    {
      "To": "receiver2@example.com",
      "Cc": "cc@example.com",
      "TemplateModel": {
        "FirstName": "Frieda"
      },
      "Metadata": {
        "color": "blue",
        "client-id": "12345"
      },
      "Headers": [
        {
          "Name": "CUSTOM-HEADER",
          "Value": "value"
        }
      ]
    },
    {
      "To": "receiver3@example.com",
      "Bcc": "bcc@example.com",
      "TemplateModel": {
        "FirstName": "Elijah"
      },
      "Metadata": {
        "color": "blue",
        "client-id": "12345"
      },
      "Headers": [
        {
          "Name": "CUSTOM-HEADER",
          "Value": "value"
        }
      ]
    }
  ]
}

Response

The /bulk endpoint will return a 200-level HTTP status when the overall request passes validation, even when validation for individual messages may fail. The response will include details on unprocessable content, if there is any. 

 

SubmittedAt string

Timestamp

ID string

ID of bulk request

Status String

Status of the bulk request. Possible options: Accepted Failed

Example response

200 OK
{
	"ID": "f24af63c-533d-4b7a-ad65-4a7b3202d3a7",
	"Status": "Accepted",
	"SubmittedAt": "2024-03-17T07:25:01.4178645-05:00"
}

422 Unprocessable Content
{
	"ErrorCode": 11,
	"Message": "Multiple errors occurred. Inspect the Errors property for more information.",
	"Errors": {
		"From": [
			{
				"ErrorCode": 300,
				"Message": "Invalid 'From' address: 'test'."
			}
		],
		"To": [
			{
				"ErrorCode": 300,
				"Message": "Invalid 'To' address: 'test'."
			}
		]
	}
}

Get the status/details of a bulk API request #

⚠️ Work in progress: This endpoint is available to early access customers only. ⚠️

Our brand new Bulk API endpoint will make it a whole lot easier for senders (like you!) to send Broadcast email at scale. This endpoint will get you the status of a bulk send request. At this point, the endpoint is available for early-access customers only. If you'd like to join the early access program (or just be notified as soon as the Bulk API is available to everyone), you can let us know here.  

get

/email/bulk/{bulk-request-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/email/bulk/{bulk-request-id}
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ID integer

ID of the request.

Status string

Possible statuses are: Accepted Processing Completed

SubmittedAt string

Timestamp of when the request was received by Postmark.

TotalMessages integer

The total number of messages in the request.

PercentageCompleted float

The percentage of sent messages at the time you make this API call.

Subject string

Email subject.

Example response

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

{
  "Id": "dc5e5d98-c073-4c97-8ee5-f897dfd28b47",
  "SubmittedAt": "2024-07-22T15:39:49.3723691Z",
  "TotalMessages": 1,
  "PercentageCompleted": 1,
  "Status": "Completed",
  "Subject": "Hello"
}