Messaging API¶

The Messaging API lets you send emails or SMS messages to an individual TrueVault user.

Email¶

TrueVault partners with third party email products to give you robust template email options. Currently, SendGrid is the only partner supported.

Before using this API, create a SendGrid account and create a transactional email template using the SendGrid web interface. Next, generate an API Key that TrueVault can use to send email on your behalf. You’ll need that API Key and the template id to send email through TrueVault.

The user making requests to the send API will also need to be in a group with a policy that grants C on User::USERID::Message or User::.*::Message

Email Request Format¶

An email request is composed of an HTTP POST with a content type of application/json and a body JSON object with the following structure:

provider: string(req’d) The email provider to deliver the message. Only SENDGRID is currently supported.
auth: object(req’d) the authentication keys issued by the email provider. This is used to send the email on your behalf and is not stored in TrueVault. For SendGrid, specify:
{ ... "auth": {"sendgrid_api_key": "YOUR_KEY_HERE"} }
template_id: string(req’d) the identifier for the email template that was created in provider.

Warning

When using Sendgrid, if the template_id is a valid GUID but not a template_id that the supplied auth can see, you will not get a 401 or a 404. Instead, due to limitations of Sendgrid’s API, you will receive a 200. A short time later, the from email address may receive an email from Sendgrid with an error message. Consequently, it’s extremely important to make sure you supply a valid template_id. Otherwise, your users will experience silent failures when sending email and may receive confusing Sendgrid error emails.
from_email_address: object(req’d) a Value Specifier (see below for details)
To supply a hard-coded from address, use a literal value specifier like this:
{ ... "from_email_address": {"literal_value": "appointment-reminders@example.com"} }
to_email_address: object(req’d) a Value Specifier (see below for details)
Deriving email_address from user attributes

In this example, the email address would be extracted from the email field in the user’s attributes document.
{ ... "to_email_address": {"user_attribute": "email"} }
Providing literal email_address

The to_email_address value provider cannot specify a literal value. That’s because it would allow a malicious user with email permissions to effectively read a user’s attributes by supplying the attacker’s email as a literal for the to_email_address field.
substitutions: object(req’d) a mapping from the substitution variable in your template and the value to substitute. Substitution values are expressed as Value Specifier objects.
Note

The keys in this mapping correspond directly to the variables in your email template and must match exactly. In the case of SendGrid, this means that if you put {{FIRST_NAME}} in your template, you need to provide {{FIRST_NAME}} to TrueVault. If you use %%FIRST_NAME%% in your template, you need to provide %%FIRST_NAME%% to TrueVault. SendGrid is flexible about the format of variables, so you can use various delimiters around your substitution variables.

Warning

Sendgrid allows substitution tokens to use ASP-style delimiters (e. g. <%NAME%>). However, because Sendgrid treats them specially they interact poorly with transaction email templates and they are not allowed.

Sample Substitutions
{ ... "substitutions": { "{{FIRST_NAME}}": {"user_attribute": "first_name"}, "{{APPOINTMENT_TIME}}: {"literal_value": "3:30pm"} } }

Template Substitution¶

You can substitute values into your email templates in two ways:

Provide literal values (e.g. substitute {{APPOINTMENT_TIME}} with "3:30pm").
Refer to values in the user’s attributes (e.g. substitute {{FIRST_NAME}} with the first_name field in the user’s attributes).

You can express these cases using a Value Specifier.

Value Specifiers¶

Values can be provided as literals in the request JSON, or loaded from the user’s attributes stored in TrueVault. These options are expressed using a Value Specifier JSON Object.

Literal Values

Literal values are expressed by a JSON Object with a field literal_value whose value is the literal value to substitute.

{"literal_value": "The Value!"}

User Attributes

Instead of specifying a literal attribute, you can tell TrueVault which field in the user’s attributes document to use. These value specifiers are JSON Objects with a field user_attribute whose value is the name of the field in the TrueVault attributes. If a value specifier references a user attribute that doesn’t exist, it will evaluate to an empty string.

For example, imagine we had a user with these attributes:

{
   first_name: "John",
   last_name: "Smith",
   email: "j.smith@example.com"
}

Then the value specifier

{"user_attribute": "first_name"}

would be converted to John. The value specifier

{"user_attribute": "email"}

would be converted to "j.smith@example.com"

System fields

Sometimes it’s useful to access user data that isn’t an attribute, like the username. This is done with JSON similar to the other types of values:

{"system_field": "username"}

Currently, username is the only supported system field.

Email a user¶

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png

POST /v1/users/(string: user_id)/message/email¶

Sends an email to the specified user.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` Content-Type – `application/json`
Parameters:	user_id – string(req’d)
Request JSON Object:
	provider(req’d) (string) – The email provider to deliver the message. Only SENDGRID is currently supported. auth(req’d) (object) – the authentication keys issued by the email provider. (see above) template_id(req’d) (string) – the identifier for the email template that was created in provider from_email_address(req’d) (object) – value specifier for from email address (see above) to_email_address(req’d) (object) – value specifier for from email address (see above) substitutions(req’d) (object) – substitutions for template (see above)

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/message/email \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "provider": "SENDGRID",
         "auth": {"sendgrid_api_key": "SG.XXXXXXXXXX"},
         "template_id": "00000000-0000-0000-0000-000000000000",
         "from_email_address": {"literal_value": "support@example.com"},
         "to_email_address": {"user_attribute": "email"},
         "substitutions": {
            "{{FIRST_NAME}}": {"user_attribute": "first_name"},
            "{{APPOINTMENT_TIME}}": {"literal_value": "3:30"},
            "{{DASHBOARD_URL}}": {"literal_value": "http://dashboard.example.com"}
         }
    }'

Example Success Response

The response includes an identifier for the generated message supplied by the email provider.

{
  "provider_message_id": "1MCQrHRdSle3tiUa4L8-mw",
  "result": "success",
  "transaction_id": "784457e9-062d-4fd0-9887-a5be8169db1e"
}

Example Error Response

If the request is invalid or the encounters an error, the HTTP status will be 4XX or 5XX as appropriate and the response JSON will include an error object describing the problem. For instance, in the case of an invalid provider auth the response might be:

{
    "error": {
        "code": 401,
        "message": "Error sending email",
        "provider_error": {
            "errors": [
                {
                    "field": null,
                    "help": null,
                    "message": "The provided authorization grant is invalid, expired, or revoked"
                }
            ]
        },
        "type": "request_failed"
    },
    "result": "error",
    "transaction_id": "a368f032-2d42-423e-bc86-50562d7ecc6c"
}

Send an SMS to a User¶

Similar to the Email API, this provides a way to send messages to your TrueVault users. It requires the same permission as sending an email, namely C on User::USERID::Message or User::.*::Message.

Currently, TrueVault provides integration with Twilio for SMS delivery. You will need your Twilio Account SID (available in the Twilio Console Dashboard), as well as an API key, which you can create in the Twilio Console. There are two kinds of Twilio API keys: “Standard” and “Master”, the latter of which has more privileges. You only need a Standard API key to be able to send SMS messages.

POST /v1/users/(string: user_id)/message/sms¶

Send an SMS to a user.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` Content-Type – `application/json`
Request JSON Object:
	provider(req’d) (string) – The SMS provider. Only `TWILIO` is currently supported. auth(req’d) (object) – Authentication info that TrueVault will pass along to the selected provider. In the case of Twilio, the object must have three keys with string values: `account_sid`, `username`, and `password`. The `account_sid` is from the Dashboard in the Twilio Console. The other two fields depend on what type of Twilio authentication info you’re using. If you’re using an API key, the `username` is the “API key SID” and the `password` is the “API key secret”. The secret is only available when you initially create an API key. If you’re using the account’s “auth token” to authenticate, the `username` is the Account SID and the `password` is the auth token. We suggest using an API key, not the auth token, as you can have multiple API keys and individually revoke them, whereas you can only have one auth token. The auth token also grants more privileges than are needed for SMS delivery. from_number(req’d) (object) – A value specifier for the number to use as the “from” number when sending an SMS. This would be a number you own via Twilio. to_number(req’d) (object) – A value specifier for the number to deliver to. To prevent leaking user attributes, this is not allowed to be a literal value spec. message_body(req’d) (string) – The string to send as the text message. media_urls(optional) (array) – Array of value specifier. Each value specifier in the array should resolve to a publicly accessible http(s) URL of an image to include with the message. Important: Since the images will be cached on telecom servers and displayed on users’ lock screens, they must not contain any protected information.

All together, a sample request might have a POST body like this:

{
  "provider": "TWILIO",
  "auth": {
    "account_sid": "... your account SID",
    "username": "... your API key SID",
    "password": "... your API key secret"
  },
  "from_number": {
    "literal_value": "+15551239876"
  },
  "to_number": {
    "user_attribute": "phone"
  },
  "message_body": "Hi there",
  "media_urls": [
    {
      "literal_value": "https://company.com/logo.png"
    },
    {
      "user_attribute": "image_url_attribute"
    }
  ]
}

The specified “to_number” would work with a user attributes document like this:

{
    "phone": "+15558675309",
    ...
}

curl https://api.truevault.com/v1/users/4a635639-fcf5-4cca-9b79-25376fdb460f/message/sms
   -X POST
   -H 'Content-Type: application/json'
   -u cfeb7f1e-a8fa-4ad9-98b1-fadad4b4fc92:
   -d '{
         "provider": "TWILIO",
         "auth": {
           "account_sid": "... your account SID",
           "username": "... your API key SID",
           "password": "... your API key secret"
         },
         "from_number": {
           "literal_value": "+19097871713"
         },
         "to_number": {
           "user_attribute": "phone"
         },
         "message_body": "Hello"
       }
       '

Example Success response

The response includes an identifier for the generated message supplied by the SMS provider.

{
  "provider_message_id": "SM038eaada04ed49a29102cd6801d71dc9",
  "result": "success",
  "transaction_id": "d12ef814-5354-4856-a124-d9d74cb73ac2"
}

Example Error Response

If the request is invalid or the encounters an error, the HTTP status will be 4XX or 5XX as appropriate and the response JSON will include an error object describing the problem. For instance, in the case of an invalid provider auth the response might be:

{
    "error": {
        "code": "",
        "message": "Error sending SMS",
        "provider_error": {
            "code": 20003,
            "http_status": 401,
            "message": "Unable to create record: Authentication Error - invalid username"
        },
        "type": "request_failed"
    },
    "result": "error",
    "transaction_id": "b26d2e72-7d9f-437b-b8a8-0312e78a7861"
}