Messages
Send message
URL
/messages
Method
POST
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
- 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.
- message (object)
Example JSON request body
Attachment content should be Base64 encoded. An attachment contentType value should be a valid MIME type.
Success response
Code: 200
Content:
Error response
Code: 400 Bad Request
Content:
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
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
- 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.
- messages (array)
Example JSON request body
Attachment content should be Base64 encoded. An attachment contentType value should be a valid MIME type.
Success response
Code: 200
Content:
Error response
Code: 400 Bad Request
Content:
List-unsubscribeList-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
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:
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 header | mailto | http |
---|---|---|
Gmail | Yes | Yes |
Gmail for mobile | No | No |
Outlook.com | Yes | No |
Yahoo! Mail | Yes | No |
Apple Mail | Yes | No |
Samsung Mail | No | No |
Windows Mail | No | No |
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:
Get email disposition
URL
/message_receipt
Method
GET
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:
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.
Error response
Code: 404 Not Found
Content: