Messages

Send message

URL

/messages

Method

POST

curl --location --request POST 'https://api.paubox.net/v1/<API_USERNAME>/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<FULL API KEY>' \
--data-raw '{
"data": {
"message": {
"recipients": [
"recipient@domain.com"
],
"headers": {
"subject": "Hello from the Paubox Email API",
"from": "sender@verifieddomain.com",
"x-custom-header": "sample custom header"
},
"content": {
"text/plain": "Hello world",
"text/html": "<html><body><h1>Hello world</h1></body></html>"
}
}
}
}'

Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.

Data parameters

  • data (object)
    • message (object)
      • recipients (array) An array of recipients as strings. Each recipient can include a name: "J. Smith <jsmith@host.com>", or not: "jsmith@email.com".
      • bcc (array, optional) An array of BCC recipient addresses. Each recipient can include a name "J. Smith <jsmith@host.com>", or not: "jsmith@email.com".
      • cc (array, optional) An array of CC recipient addresses. Same format as for BCC for each entry in the array.
      • headers (object)
        • subject (string) Message subject.
        • from (string) Message "from" address. This must match the verified domain of your API key.
        • reply-to (string, optional) reply-to address (if different than "from"). This must match the verified domain of your API key.
        • List-Unsubscribe (string, optional) The List-Unsubscribe header provides two methods of unsubscribing users: an email unsubscribe, and a web unsubscribe. One, or both, of these methods may be used. More details here
        • List-Unsubscribe-Post (string, optional) Used in conjunction with List-Unsubscribe header. More details here
        • X-<Custom-Header-Name> (string, optional) Adds custom headers to the message payload. Simply prepend X- to a custom header name and supply a value.
      • allowNonTLS (boolean, defaults to false, optional) Set to true to allow message delivery over non-TLS connections rather than converting the message into a Secure Portal message when a non-TLS connection is encountered. This is not HIPAA-compliant if the message contains PHI.
      • forceSecureNotification(boolean, defaults to false, optional) Set to true to force message delivery through a Paubox Secure Message. The recipient will be emailed a pickup notification with a link to a secure message hosted by Paubox rather than the contents of the message itself.
      • content (object)
        • text/plain (string, optional if message has text/html part). Plain text version of message body.
        • text/html (string, HTML-escaped, base64-encoded or valid unescaped string. Optional if message has text/plain part). HTML version of message body. CSS can be included in <style> tags in the head section of the document or inline on the elements. CSS in <style> tags will be rendered inline.
      • attachments (array[object], optional) An array of objects representing file attachments.
        • fileName (string) The filename, including the file extension.
        • contentType (string) A valid MIME type (e.g. "application/pdf").
        • content (string) Base64 encoded contents of the file.

Example JSON request body

{
"data": {
"message": {
"recipients": [
"recipient@host.com",
"Recipient Name <recipient2@host.com>"
],
"bcc": ["recipient3@host.com", "Recipient Name <recipient4@host.com>"],
"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>",
"x-custom-header": "sample custom header"
},
"allowNonTLS": false,
"forceSecureNotification": false,
"content": {
"text/plain": "Hello World!",
"text/html": "<html><body><h1>Hello World!</h1></body></html>"
},
"attachments": [
{
"fileName": "hello_world.txt",
"contentType": "text/plain",
"content": "SGVsbG8gV29ybGQh"
}
]
}
}
}

Attachment content should be Base64 encoded. An attachment contentType value should be a valid MIME type.

Success response

Code: 200
Content:

{
"sourceTrackingId": "3d38ab13-0af8-4028-bd45-52e882e0d584",
"data": "Service OK"
}

Error response

Code: 400 Bad Request
Content:

{
"errors": [
{
"code": 400,
"title": "Error Title",
"details": "Description of error"
}
]
}

Send bulk messages

We recommend batches of 50 (fifty) or less. Source tracking ids are returned in order messages appear in the messages array.

URL

/bulk_messages

Method

POST

curl --location --request POST 'https://api.paubox.net/v1/<API_USERNAME>/bulk_messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token token=<FULL API KEY>' \
--data-raw '{
"data": {
"messages": [
{
"recipients": [
"recipient@domain.com"
],
"headers": {
"subject": "Hello from the Paubox Email API",
"from": "sender@verifieddomain.com",
"x-custom-header": "sample custom header"
},
"content": {
"text/plain": "Hello world",
"text/html": "<html><body><h1>Hello world</h1></body></html>"
}
},
{
"recipients": [
"recipient@domain.com"
],
"headers": {
"subject": "Hello from the Paubox Email API",
"from": "sender@verifieddomain.com",
"x-custom-header": "sample custom header"
},
"content": {
"text/plain": "Hello world",
"text/html": "<html><body><h1>Hello world</h1></body></html>"
}
}
]
}
}'

Replace <USERNAME> with your API endpoint username and <API_KEY> with your API key.

Data parameters

  • data (object)
    • messages (array)
      • recipients (array) An array of recipients as strings. Each recipient can include a name: "J. Smith <jsmith@host.com>", or not: "jsmith@email.com".
      • bcc (array, optional) An array of BCC recipient addresses. Each recipient can include a name "J. Smith <jsmith@host.com>", or not: "jsmith@email.com".
      • cc (array, optional) An array of CC recipient addresses. Same format as for BCC for each entry in the array.
      • headers (object)
        • subject (string) Message subject.
        • from (string) Message "from" address. This must match the verified domain of your API key.
        • reply-to (string, optional) reply-to address (if different than "from"). This must match the verified domain of your API key.
        • List-Unsubscribe (string, optional) The List-Unsubscribe header provides two methods of unsubscribing users: an email unsubscribe, and a web unsubscribe. One, or both, of these methods may be used. More details here
        • List-Unsubscribe-Post (string, optional) Used in conjunction with List-Unsubscribe header. More details here
        • X-<Custom-Header-Name> (string, optional) Adds custom headers to the message payload. Simply prepend X- to a custom header name and supply a value.
      • allowNonTLS (boolean, defaults to false, optional) Set to true to allow message delivery over non-TLS connections rather than converting the message into a Secure Portal message when a non-TLS connection is encountered. This is not HIPAA-compliant if the message contains PHI.
      • forceSecureNotification(boolean, defaults to false, optional) Set to true to force message delivery through a Paubox Secure Message. The recipient will be emailed a pickup notification with a link to a secure message hosted by Paubox rather than the contents of the message itself.
      • content (object)
        • text/plain (string, optional if message has text/html part). Plain text version of message body.
        • text/html (string, HTML-escaped, base64-encoded or valid unescaped string. Optional if message has text/plain part). HTML version of message body. CSS can be included in <style> tags in the head section of the document or inline on the elements. CSS in <style> tags will be rendered inline.
      • attachments (array[object], optional) An array of objects representing file attachments.
        • fileName (string) The filename, including the file extension.
        • contentType (string) A valid MIME type (e.g. "application/pdf").
        • content (string) Base64 encoded contents of the file.

Example JSON request body

{
"data": {
"messages": [
{
"recipients": [
"recipient@host.com",
"Recipient Name <recipient@host.com>"
],
"bcc": ["recipient3@host.com", "Recipient Name <recipient4@host.com>"],
"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>",
"x-custom-header": "sample custom header",
},
"allowNonTLS": false,
"forceSecureNotification": false,
"content": {
"text/plain": "Hello World!",
"text/html": "<html><body><h1>Hello World!</h1></body></html>"
},
"attachments": [
{
"fileName": "hello_world.txt",
"contentType": "text/plain",
"content": "SGVsbG8gV29ybGQh"
}
]
},
{
"recipients": [
"recipient2@host.com",
"Recipient Name <recipient2@host.com>"
],
"bcc": ["recipient3@host.com", "Recipient Name <recipient4@host.com>"],
"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>"
},
"allowNonTLS": false,
"forceSecureNotification": false,
"content": {
"text/plain": "Hello World!",
"text/html": "<html><body><h1>Hello World!</h1></body></html>"
},
"attachments": [
{
"fileName": "hello_world.txt",
"contentType": "text/plain",
"content": "SGVsbG8gV29ybGQh"
}
]
}
]
}
}

Attachment content should be Base64 encoded. An attachment contentType value should be a valid MIME type.

Success response

Code: 200
Content:

{
"messages": [
{
"sourceTrackingId": "3d38ab13-0af8-4028-bd45-999999999999",
"data": "Service OK"
},
{
"sourceTrackingId": "3d38ab13-0af8-4028-bd45-000000000000",
"data": "Service OK"
}
]
}

Error response

Code: 400 Bad Request
Content:

{
"errors": [
{
"code": 400,
"title": "Error Title",
"details": "Description of error"
}
]
}

List-unsubscribe

List-Unsubscribe is a small piece of text that can be inserted in the header section of your email. The List-Unsubscribe header will insert an “unsubscribe” button, or link, next to the From address at the top of your email. A recipient can click this link to notify you that they would like to unsubscribe from your emails.

Example JSON request body (header portion) with list-unsubscribe header

"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>",
"List-Unsubscribe": "<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>"
}

How does the list-unsubscribe header work?

The List-Unsubscribe header provides two methods of unsubscribing users: an email unsubscribe, and a web unsubscribe. One, or both, of these methods may be used.

Email unsubscribe: mailto

The mailto portion of the List-Unsubscribe header allows you to specify an email address that will receive the unsubscribe request. In other words, when a recipient clicks the “unsubscribe” link in your email, the recipient’s mail client will send an email to this address.

It is your responsibility to receive and process these generated emails.

Web unsubscribe: http

With the http method, behind the list-unsubscribe header, there is a URL leading to a web page for opting out. When a user clicks the unsubscribe link, a landing page opens, and the user is asked to confirm unsubscription. Here is the flow of setting up an http list-unsubscribe:

  • Create a web page dedicated to unsubscribe requests. Both http: and https: are acceptable. For example, http://www.example.com/unsubscribe.html
  • Provide the unsubscribe URL to your email administrator or ESP, and ask them to insert it into the email header. It is best to use this method in conjunction with mailto because the recipient’s inbox client may not support http list-unsubscribe. That’s why it is advisable to use the following syntax:
"headers": {
"subject": "sample email",
"from": "sender@authorized_domain.com",
"reply-to": "Sender Name <sender@authorized_domain.com>",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe.html>"
}

Also, make sure a user does not need to enter credentials or select a checkbox to complete the unsubscription process. One-click list-unsubscribe From a user’s perspective, one-click functionality for the list-unsubscribe is awesome. It spares them the requirement of providing additional confirmation on a landing page. The unsubscribe decision is simply made with one click. From a marketer’s perspective, this option is a killer. On the landing page, users may change their mind and recall unsubscription.

Which method should I choose?

“Both” is the best answer. Unfortunately, not all email clients support the http method. If you bet on using it alone, you run the risk of damaging your sender reputation. With mailto list-unsubscribe provided as an alternative, your sender reputation is better protected and your recipients are all able to accomplish the unsubscribe function.

Which email clients support list-unsubscribe header

list-unsubscribe headermailtohttp
GmailYesYes
Gmail for mobileNoNo
Outlook.comYesNo
Yahoo! MailYesNo
Apple MailYesNo
Samsung MailNoNo
Windows MailNoNo

Tools to check list-unsubscribe and spamminess of your emails

Let’s say, you’ve set up the list-unsubscribe header to you email campaign. Check out whether it works by sending an email to a test inbox. For Gmail, you’ll see the unsubscribe option in the header right next to the sender name. Also, you can verify headers in detail. For this, click the three dots near the Reply button and choose “Show original” in the dropdown menu.

You’ll see information about the main headers like Message-ID, To:, and others. List-unsubscribe won’t be there; you’ll need to search for it as well as for the method used (mailto, http or both). It may look like this:

List-Unsubscribe: <mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe.html>

Get email disposition

URL

/message_receipt

Method

GET

curl -X GET \
https://api.paubox.net/v1/<USERNAME>/message_receipt?sourceTrackingId=<SOURCE_TRACKING_ID> \
-H 'authorization: Token token=<API_KEY>' \
-H 'content-type: application/json'

Replace <USERNAME> with your API endpoint username, <SOURCE_TRACKING_ID> with the message's sourceTrackingId, and <API_KEY> with your API key.

Success response

Code: 200
Content:

{
"sourceTrackingId": "6e1cf9a4-7bde-4834-8200-ed424b50c8a7",
"data": {
"message": {
"id": "<f4a9b518-439c-497d-b87f-dfc9cc19194b@authorized_domain.com>",
"message_deliveries": [
{
"recipient": "recipient@host.com",
"status": {
"deliveryStatus": "delivered",
"deliveryTime": "Mon, 23 Apr 2018 13:27:34 -0700",
"openedStatus": "opened",
"openedTime": "Mon, 23 Apr 2018 13:27:51 -0700"
}
}
]
}
}
}

Note that openedStatus and openedTime are only available on messages with a single recipient.

deliveryStatus

deliveryStatus will return one of the following strings for each message delivery.

"processing"
"TLS not offered, sending via Secure Portal"
"soft bounced"
"soft bounced - mailbox full"
"hard bounced"
"Internal error. Please check back later."
"delivered"
"delivered via secure portal"

Error response

Code: 404 Not Found
Content:

{
"errors": [
{
"code": 404,
"title": "Message was not found",
"details": "Message with this tracking id was not found"
}
],
"sourceTrackingId": "6e1cf9a4-7bde-4834-8d200-ed424b50c8a7"
}