Developer Guide

Connecting to the Send It Secure SMTP Service

Overview

The Send It Secure SMTP Service is an easy way to send secure email from any application that can send email using SMTP, helping you meet HIPAA and other compliance regulations.

• Each recipient counts as one send. For example, a single message sent to 3 recipients counts as 3 sends.

How to connect to the Send It Secure SMTP Service

1. Create API access credentials to use as your SMTP username and password.

   Create an access credential - Send It Secure Help Center

2. Send using these SMTP server settings:

   SMTP Setting	Value
   Hostname:	smtp.protectedtrust.com
   Port:	587 (or 25)
   Encryption:	STARTTLS (or TLS)
   Username:	Your API Access ID or Email Address
   Password:	Your API Access Key

Limitations

• The maximum message size after being MIME-decoded is 50 MB.

.NET Example Code

// create a message
MailMessage message = new MailMessage();
message.To.Add("joe@example.com");
message.From = new MailAddress("reminders@hcareclinic.com");

// Note: The subject of a protected message is NOT encrypted and should not contain sensitive information
message.Subject = "Appointment reminder";

// The message is encrypted
message.IsBodyHtml = false; message.Body = "Hello Joe, This is a reminder that you have an appointment at 9:30 AM on Tuesday, April 3 with Dr. Smith.nn";

// append the optional XML fragment for recipient identity verification 
message.Body += "\n\n<protectedtrust><registered>yes</registered><phone>1999-555-9999</phone></protectedtrust>";

// create an smtp client
using (SmtpClient smtpClient = new SmtpClient("smtp.protectedtrust.com", 587)) 
{ 
    // configure the client 
    smtpClient.EnableSsl = true;

    // The access credential generated for your API account.
    string accessID = "X";
    string accessKey = "Y";
    smtpClient.Credentials = new NetworkCredential(accessID, accessKey);
    
    // send it
    smtpClient.Send(message);
}

Advanced Features

To use more features of Send It Secure messages, add the optional <protectedtrust> XML fragment to the body of your messages. See the following sections for details on each feature.

Example:

<protectedtrust>
  <phone>8635941141</phone>
  <receipt>Y</receipt>
</protectedtrust>

Recipient Identity Verification Methods

There are four identity verification options (see examples below for more complete examples).

Note: If the <protectedtrust> XML is present, the verification method must be included. If the <protectedtrust> XML is not present, the default verification method will be Required Registration.

Example:

Note: Each recipient in the To, Cc, and Bcc MIME headers must also exist in the XML fragment.

<protectedtrust>
  <recipient>
    <email>example1@protectedtrust.com</email>
    <sharedsecret>
      <question>What is the secret code?</question>
      <answer>12345</answer>
    </sharedsecret>
  </recipient>
  <recipient>
    <email>example2@protectedtrust.com</email>
    <phone>8635941141</phone>
  </recipient>
  ... other options ...
</protectedtrust>

If your message has only one recipient, then the <recipient> and <email> elements are not required.

<protectedtrust>
  <phone>8635941141</phone>
  ... other options ...
</protectedtrust>

Message Expiration (Optional)

Message expiration allows a sender to choose when a message will no longer be available to recipients. The expiration values available to a sender are controlled by the selected message policy. By default, messages do not expire but a recipient will lose access to a message at the end of his or her retention period. Each recipient may have a different retention period, which range from 30 days for free users up to 10 years. If you want to ensure that a message expires within a certain time period, utilize the <expire> option.

Example with 14-day expiration:

<protectedtrust>
  ... other options ...
  <expire>14</expire>
</protectedtrust>

Receipt Notification (Optional)

Specify Y or N to enable/disable receipt notification. When enabled, a notification email will be sent to the sender when each recipient views the message.

Example:

<protectedtrust>
  ... other options ...
  <receipt>Y</receipt>
</protectedtrust>

Custom Message Policies (Optional)

When your organization is configured with multiple message policies, specify the ID you'd like to use here. The ID can be extracted from the URL while editing the message policy. For example, it's the last part of this URL: https://app.protectedtrust.com/MessagePolicy/Edit/Df45Qyu77arBOmyVpTggji.

Example:

<protectedtrust>
  ... other options ...
  <messagepolicyid>Df45Qyu77arBOmyVpTggji</messagepolicyid>
</protectedtrust>

Custom Text in Notification Email (Optional)

When an encrypted email is sent, the recipient receives a notification email that includes a link to the actual message. Parts of this notification email can be customized using a custom message policy (see above) and can be further customized on a per-message basis by passing the desired text in the <protectedtrust> XML.

1) If you don't already have one, create a default custom message policy for your account. This will become the primary message policy that your company uses when not using this API. Message policies can be configured on the Send It Secure web portal, under Dashboard -> Message Policies.

2) Create a second custom message policy that will be used only by this API. Using a second, non-default message policy is needed so that messages sent without using this API continue to format properly.

3) While editing the second message policy, under Templates modify the Recipient Notification Body to be just $(Body).

4) Note the message policy ID from the URL while editing the policy and specify it in the <messagepolicyid> element. For example, the message policy ID is the last part of this URL: https://app.protectedtrust.com/MessagePolicy/Edit/Df45Qyu77arBOmyVpTggji.

Example:

<protectedtrust>
  ... other options ...
  <messagepolicyid>Df45Qyu77arBOmyVpTggji</messagepolicyid>
  <notification>
    <body>Click 'View Message' below to open this secure message.  For assistance, please contact me at (888) 555-1212.</body>
  </notification>
</protectedtrust>

Link to a Sent Message in your Application (Optional)

You can also assign an external ID to messages you send. This lets you create a link in your application that can be used to view a sent message directly. For example, you could put a link in a patient history chart that opens the sent message in Send It Secure.

To use this functionality, you must acquire a partner code from Send It Secure. Please contact us for more information.

To open the sent message, direct the user to a URL using this format: https://app.protectedtrust.com/ExternalPickup/{PartnerCode}/{ID}. In the example below, the URL would be https://app.protectedtrust.com/ExternalPickup/EXAMPLEPARTNER/1b34c2c0-3f65-4ac8-a245-389e28cf9339

<protectedtrust>
   ... recipient options ...
   <externalpickup>
      <partnercode>EXAMPLEPARTNER</partnercode>
      <id>1b34c2c0-3f65-4ac8-a245-389e28cf9339</id>
   </externalpickup>
</protectedtrust>

IP-based Authorization

If your sending mail system does not have the ability to send a username/password to our SMTP gateway, you can configure IP-based authorization.

To enable this feature, please contact us.

Once the feature is enabled, follow these steps:

1. Sign in at https://app.protectedtrust.com/login as an administrator
2. Navigate to the User List page
3. Click on the service user in the list (i.e. results@mylab.com)
4. Click on the "API & SMTP Settings" link
5. Create an Access Credential
6. Click Edit on it
7. Add your IP Address to the field, "Auto-Authorize these IP Addresses" and Save