Messages


Send Message

URL

/messages

Method

POST

curl -X POST \
https://api.paubox.net/v1/<USERNAME>/messages \
-H 'authorization: Token token=<API_KEY>' \
-H 'content-type: application/json' \
-d '{ \
"data": { \
"message": { \
"recipients": [ \
"recipient@host.com" \
], \
"headers": { \
"subject": "Hello from the Paubox Email API!", \
"from": "sender@authorized_domain.com" \
}, \
"content": { \
"text/plain": "Hello World!" \
} \
} \
} \
}'

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

Data Param

  • 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".
      • 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.
      • 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>"
},
"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\n"
}
]
}
}
}

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

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