We use cookies to make interactions with our website and services relevant to you by better understanding your use and to tailor advertising. See our full policy for details.

Paubox Email API

A HITRUST CSF Certified email API for developers and IT professionals.

Start for Free

A Secure Email Api For Healthcare Providers And Developers

Email stack

Paubox's HIPAA compliant encrypted email API allows hospitals, health management organizations (HMOs), clinics, doctors, and other covered entities to integrate Paubox's seamless and secure email solution with their IT infrastructure. The uses range from integrating with patient portals to securing website contact forms.

This API also allows third-party developers who are creating innovative healthcare IT solutions to focus on their applications instead of building and maintaining a HIPAA compliant email server. This can help developers get to market faster and quickly integrate a seamless email product that works on desktops, laptops, smartphones, tablets and wearables.

Take advantage of Paubox's experience with maintaining HIPAA compliance with email and focus on innovation.

Features & Benefits



Optimize Your IT

Paubox can secure every email sent from EHRs and patient portals seamlessly so recipients can view messages without the inconvenience of logging into web portals or downloading apps. Any IT system that sends email can be secured, even scanners.


Focus on Innovation

Third-party developers creating innovative healthcare solutions can focus on their apps instead of building and maintaining a HIPAA compliant email server.


Leverage our Tech

Use Paubox’s industry expertise and patent-pending email encryption that makes it easy to send and receive HIPAA compliant email. No plug-ins. No software. Just email.


Business Associate Agreements

Not having a BAA in place with your vendors could have you facing steep fines. Paubox will sign a BAA to make sure you stay HIPAA compliant.


Professional Services

Need hands-on help getting setup? Ask about our professional services, where our expert technical support can get you on the right track.



Documentation

The Paubox Email API provides two ways to send email: Via REST or SMTP.



Paubox REST API

Send HIPAA compliant emails and obtain email delivery information with the Paubox REST API. Use one of our SDKs for a quick and easy implementation or see documentation below for API end points and examples.

Paubox SDKs

Leverage our SDKs to efficiently implement the Paubox Email API.

Paubox Client Libraries Installation
Node.js GitHub
Ruby GitHub
Ruby on Rails GitHub
Python GitHub
C# GitHub
Java GitHub
PHP GitHub
Perl GitHub

Paubox Email REST API v1

Base URL

https://api.paubox.net/v1/<USERNAME>

Date Format

Dates are passed as strings formatted to RFC 2822 standards e.g. "Fri, 16 Feb 2018 13:00:00 GMT"

Standard HTTP response codes

Status Code Status Message
200 Service OK
400 Bad Request
401 Unauthorized
404 Not Found
500, 502, 503, 504 Server Error

Endpoints

Send Message

POST /messages

      
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.

Definition
Request Body Schema
  • 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.
        • 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.
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.

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

Use the sourceTrackingId to request email disposition later.

400 Bad Request
      
{
  "errors": [
    {
      "code": 400,
      "title": "Error Title",
      "details": "Description of error"
    }
  ]
}
Get Email Disposition

GET /message_receipt

      
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.

Responses
200 OK
      
{
  "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"
404 Not Found
      
{
  "errors": [
    {
      "code": 404,
      "title": "Message was not found",
      "details": "Message with this tracking id was not found"
    }
  ],
  "sourceTrackingId": "6e1cf9a4-7bde-4834-8d200-ed424b50c8a7"
}

Paubox SMTP Relay Service

Send Paubox encrypted emails from your email application and authenticate using your IP address. The SMTP relay is the easiest to configure, as it only requires modifying SMTP configuration.

  • Set the server host name to outbound.paubox.com
  • Use port 25 or 587 for TLS connections. Unencrypted connections are not allowed.

We strongly discourage users from sending mail directly through a single specific IP address when integrating with Paubox. Always point your traffic to outbound.paubox.com

The IP addresses at outbound.paubox.com are changed often and without notice. If you point your traffic to one specific IP, you will experience interruptions in your service when these IPs are changed.

Paubox SMTP Server

Send Paubox encrypted emails from your email application and authenticate using login.

Here's how to use the Paubox SMTP Server with nodemailer 

        
var nodemailer = require("nodemailer");
var smtpTransport = require("nodemailer-smtp-transport");
var transporter = nodemailer.createTransport(smtpTransport({
  "port": 587,
  "host": "api.paubox.com",
  "auth": {
    "user": "user@api.paubox.com",
    "pass": "password"
  },
  "tls": {
    "rejectUnauthorized": false
  }
}));

transporter.sendMail({
  from: "from@server.com",
  to: "to@server.com",
  subject: "Subject",
  html: "html body",
  text: "text body"
  // etc
}, function (err) {
  // error handling
});

Here's how to use the Paubox SMTP Server with Ruby on Rails Action Mailer 

        
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  :address   => "api.paubox.com",
  :port      => 587,
  :user_name => "user@api.paubox.com",
  :password  => "<password>",
  :enable_starttls_auto => true,
  :authentication => "plain",
}

Here's how to use the Paubox SMTP Server with PHP 

        
<?php
require_once "Mail.php";
// SMTP authentication params
$smtp_params["host"]     = "api.paubox.com";
$smtp_params["port"]     = "587";
$smtp_params["auth"]     = true;
$smtp_params["username"] = "user@api.paubox.com";
$smtp_params["password"] = "<password>";
?>

Here's how to use the Paubox SMTP Server with C# 

        
MailMessage mail = new MailMessage();
SmtpClient SmtpServer = new SmtpClient("api.paubox.com");
mail.From = new MailAddress("your_email_address");
mail.To.Add("recipient_email_address");
mail.Subject = "Test Mail";
mail.Body = "Hello World";
SmtpServer.Port = 25;
SmtpServer.Credentials = new System.Net.NetworkCredential("user@api.paubox.com", "<password>");
SmtpServer.EnableSsl = true;
SmtpServer.Send(mail);
MessageBox.Show("mail Send");

and here's how to use the Paubox SMTP Server with Python 

        
#!/usr/bin/python

import smtplib

USERNAME = "user@api.paubox.com"
PASSWORD = "password"
FROM = USERNAME
TO = ["recipient@example.com"]
SUBJECT = "subject"
TEXT = "text body"

message = """From: %s\nTo: %s\nSubject: %s\n\n%s""" 
% (FROM, ", ".join(TO), SUBJECT, TEXT)

server = smtplib.SMTP("api.paubox.com", 587)
server.ehlo()
server.starttls()
server.login(USERNAME, PASSWORD)
server.sendmail(FROM, TO, message)
server.close()