Email API

A HIPAA compliant email API for developers and IT professionals

An Email Api For Healthcare Providers And Developers

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.

Start Your Free Trial Today

Once we did our due diligence, there was no doubt we would go with Paubox

Bhupendra Sheoran, Executive Director

YTH

How many messages do you send each month?

$100/mo ($1,200 billed annually) No charge until after your 14-day free trial

Documentation

Paubox API provides two ways to send email: through REST or through 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

Implement Paubox HIPAA compliant email with a few lines using our SDKs.

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

Paubox 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 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.
  - 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()