Sending Personalized Email with TrueVault

TrueVault has partnered with SendGrid to send personalized emails to your customers using the TrueVault API. This post walks you through the integration process and shouldn't take more than fifteen minutes to complete.

Setup in SendGrid

The first thing to do is setup a new SendGrid Account. If you just want to try this out, you can take advantage of SendGrid's generous free plan, which lets you send 12k emails per month.

Transactional Template

Log in to your fancy new SendGrid account and create a Transactional Template. Once you've created it, click "Add Version" and give it the following content:

    Subject: Appointment Reminder
    Body:
    ,

    This is a courtesy email to remind you of your appointment tomorrow at .

Grab the ID of the template from SendGrid and note that for later.

API Key

To allow TrueVault to send emails on your behalf, you'll need to create a SendGrid API Key. In SendGrid, navigate to your account settings and create a new API Key with permission to send email (as shown below). Keep this API Key handy, you'll send it to the TrueVault API every time you want to send an email to your users.

TrueVault

Now that you have your template setup in SendGrid, you can use the TrueVault email API to send emails populated with information stored in TrueVault. Let's create a user for this example with these attributes:

    {
        "first_name": "Cody",
        "last_name": "Coderson",
        "email": "cody@example.com"
    }

You can create this user through your application, curl, or you can use our management console to create a new user like this:

Now let's put the pieces together and send this user an appointment reminder. You'll make an API call to TrueVault like this:

curl https://api.truevault.com/v1/users/[USER_ID]/message/email \
   -X POST \
   -H 'Content-Type: application/json' \
   -u '[API_KEY]:' \
   -d '{
        "provider": "SENDGRID",
        "auth": {"sendgrid_api_key": "[YOUR KEY HERE]"},
        "template_id": "[YOUR TEMPLATE ID HERE]",
        "from_email_address": {"literal_value": "support@supercoolapp.com"},
        "to_email_address": {"user_attribute": "email"},
        "substitutions": {
           "": {"user_attribute": "first_name"},
           "": {"literal_value": "3:30pm"}
        }
   }'

This request will result in an email to cody@example.com like this:

    Subject: Appointment Reminder
    Body:
    Cody,

    This is a courtesy email to remind you of your appointment tomorrow at 3:30pm.

Let's break that down. We use secure data stored in TrueVault to populate the user's email address and first name. That data never has to touch your server, which can save you from all the headaches that come with running HIPAA-compliant infrastructure. In addition to the TrueVault data, we want to add some information that comes from another system. In this case, it's the appointment time. We pass that substitution as a literal value specifier.

Security & Compliance Caution

This email functionality can be used for a variety of communications with users, but should never be used to send sensitive information directly. If you'd like to communicate sensitive information to the user, don't put it in the email body. Instead, send them an email that tells them their attention is required in your system, and give them a link to view the information. Then you can protect the sensitive information behind an authenticated endpoint in your web or mobile application.

Authorization

We have created a special permission for sending messages to users. An authorized user must be in a group that has the C Activity on the User::[USERID]::Message resource. You can see more details in our Group Policy Access Grid. It is important to note that having this permission is orthogonal to having the ability to read a user. This can be really helpful if you want to trigger email sending from your own server. Instead of using an API Key for a user that has full read access to other users, you can authenticate as a user that can only send email. Then, if your server is compromised, the worst an attacker can do is email your users (not great, but far better than reading all their data).

How did it go?

I hope the integration went smoothly for you! If you have any problems, or want to see something added, let us know! You can find full documentation for our email functionality here.

Have more questions? Try asking on StackOverflow and tag your question with truevault.