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

Overview

Integration

User guide

API reference

Webhooks

Bulk Email

Send bulk emails #

/email/bulk

Request headers

Example request with curl

Body format

Example body format

Response

Example response

Get the status/details of a bulk API request #

/email/bulk/{bulk-request-id}

Request headers

Example request with curl

Response

Example response