Sending an Email

TMS provides a flexible and easy way for your application to push notifications to your users. In this tutorial, we’ll walk through a couple of scenarios for using TMS to send static or customized emails to users.

After this tutorial, be sure to look at the /messages/email endpoint reference documents for more information on how to view and manage the emails you send via TMS.

Prerequisites

Before you can send an email, there are a few things your organization will need to do to enable the Targeted Messaging Service:

Purchase the Targeted Messaging Service
Configure email addresses for the Targeted Messaging Service
Get a Targeted Messaging Service API Token

To get started on any of these, please email support@granicus.com.

Send a Simple Email to One Person

Once you’ve covered the prerequisites, sending an email is simple. The first thing you need to do is decide who you’re going to email, and what you want to say. Let’s send a simple hello to Jim with an email like the following:

To: jim@example.com
From: me@example.com
Subject: Hello!

Hi!

Now that you know what we want to send, it’s simply a matter of making a POST to /messages/email with subject, body, and recipients specified to what you want. TMS then responds with the JSON below.

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "subject": "Hello!",
  "body": "Hi!",
  "recipients": [
    {
      "email": "jim@example.com"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 2715041,
  "subject": "Hello!",
  "body": "Hi!",
  "click_tracking_enabled": true,
  "errors_to": "errors@example.com",
  "from_email": "me@example.com",
  "from_name": "Me",
  "macros": null,
  "open_tracking_enabled": true,
  "reply_to": "reply@example.com",
  "message_type_code": null,
  "created_at": "2016-06-06T15:30:35Z",
  "status": "new",
  "_links": {
    "self": "/messages/email/2715041",
    "recipients": "/messages/email/2715041/recipients",
    "failed": "/messages/email/2715041/recipients/failed",
    "sent": "/messages/email/2715041/recipients/sent",
    "clicked": "/messages/email/2715041/recipients/clicked",
    "opened": "/messages/email/2715041/recipients/opened"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
email = client.email_messages.build(subject:'Hello!',
                                    body:'Hi!')
email.recipients.build(email:'jim@example.com')
email.post
=> true

Once this POST is sent, TMS will send your email, with the From email header set to the default from_address for your account.

Send a Simple Email to Multiple People

At some point, you’ll probably want to send an email to more than one person. This is just as simple to do with TMS as sending an email to a single person - all you need to do is specify multiple recipients. Let’s send our hello message again, but this time to a few more people:

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "subject": "Hello!",
  "body": "Hi!",
  "recipients": [
    {
      "email": "jim@example.com"
    },
    {
      "email": "amy@example.com"
    },
    {
      "email": "bill@example.com"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 2689562,
  "subject": "Hello!",
  "body": "Hi!",
  "click_tracking_enabled": true,
  "errors_to": "errors@example.com",
  "from_email": null,
  "from_name": null,
  "macros": null,
  "open_tracking_enabled": true,
  "reply_to": "reply@example.com",
  "message_type_code": null,
  "created_at": "2016-06-06T15:22:48Z",
  "status": "new",
  "_links": {
    "self": "/messages/email/2689562",
    "recipients": "/messages/email/2689562/recipients",
    "failed": "/messages/email/2689562/recipients/failed",
    "sent": "/messages/email/2689562/recipients/sent",
    "clicked": "/messages/email/2689562/recipients/clicked",
    "opened": "/messages/email/2689562/recipients/opened"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
email = client.email_messages.build(subject:'Hello!',
                                    body:'Hi!')
email.recipients.build(email:'jim@example.com')
email.recipients.build(email:'amy@example.com')
email.recipients.build(email:'bill@example.com')
email.post
=> true

Again, once this POST is sent, TMS will send your email to every recipient you specify.

In both of our examples, you’ve probably noticed that TMS also sends you a response with a number of properties. Among these properties are a set of URLs (all found in the _links object) that you can request to review the email you sent and check its status, review the status of all of the recipients you specified for your email, retrieve lists of recipients who have received your email and recipients who TMS could not deliver your email to, and retrieve lists of recipients who have opened your email and recipients who have clicked a link in your email.

Send Custom Emails to People with Macros

As a final exercise, let’s consider customizing our email messages for each of our recipients. TMS makes this easy to do in a single request by allowing you to create macros and define those macros for each of your recipients.

It’s time to send our hello message again to our three recipients. This time, we’ll create a [[name]] macro and customize it for each recipient. We’ll also make our message a bit prettier with some HTML.

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "subject": "Hello!",
  "body": "<p>Hi <span style=\"color:red;\">[[name]]</span>!</p>",
  "macros": {
    "name": "there"
  },
  "recipients": [
    {
      "email": "jim@example.com",
      "macros":{
        "name":"Jim"
      }
    },
    {
      "email": "amy@example.com",
      "macros":{
        "name": "Amy"
      }
    },
    {
      "email": "bill@example.com"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 2689559,
  "subject": "Hello!",
  "body": "<p>Hi <span style=\"color:red;\">[[name]]<\/span>!<\/p>",
  "click_tracking_enabled": true,
  "errors_to": "errors@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
    "name": "there"
  },
  "open_tracking_enabled": true,
  "reply_to": "reply@example.com",
  "message_type_code": null,
  "created_at": "2016-06-06T15:15:36Z",
  "status": "new",
  "_links": {
    "self": "/messages/email/2689559",
    "recipients": "/messages/email/2689559/recipients",
    "failed": "/messages/email/2689559/recipients/failed",
    "sent": "/messages/email/2689559/recipients/sent",
    "clicked": "/messages/email/2689559/recipients/clicked",
    "opened": "/messages/email/2689559/recipients/opened"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
email = client.email_messages.build(subject:'Hello!',
                                    body:'<p>Hi <span style="color:red;">[[name]]</span>!</p>',
                                    macros:{"name"=>"there"})
email.recipients.build(email:'jim@example.com', macros:{"name"=>"Jim"})
email.recipients.build(email:'amy@example.com', macros:{"name"=>"Amy"})
email.recipients.build(email:'bill@example.com')
email.post
=> true

Notice that when we create macros, we must set default values for those macros by adding a macros attribute to the email object we’re POSTing. These default values will be used for macros when we don’t specify a value for a macro for a recipient. In the above example, bill@example.com will receive an email that says Hi there!, while jim@example.com will receive Hi Jim! and amy@example.com will receive Hi Amy!.

Send an Email Using a Template

You can use templates to send a message:

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "recipients": [
    { 
      "email": "jim@example.com", 
      "macros": {
          "name":"Jim",
          "confirmationUrl": "http://example.com/confirm?t=1234abcd"
      } 
    },
    { 
      "email": "amy@example.com", 
      "macros": {
          "name": "Amy",
          "confirmationUrl": "http://example.com/confirm?t=9876zyxw"
      } 
    },
    { 
      "email": "bill@example.com"
    }
  ], 
  "_links": {
    "email_template": "new-template"
  }
}'

// RESPONSE BODY
{
  "subject":"Welcome!",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "click_tracking_enabled": false,
  "errors_to": "me@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
      "name":"New User"
  },
  "open_tracking_enabled": false,
  "reply_to": "me@example.com",
  "created_at": "2015-05-05T20:02:20Z",
  "status": "new",
  "_links": {
      "self": "/messages/email/10287",
      "recipients": "/messages/email/10287/recipients",
      "failed": "/messages/email/10287/recipients/failed",
      "sent": "/messages/email/10287/recipients/sent",
      "clicked": "/messages/email/10287/recipients/clicked",
      "opened": "/messages/email/10287/recipients/opened",
      "email_template":"/templates/email/new-template"
  }
}

email = client.email_messages.build
email.links[:email_template] = template.uuid
email.recipients.build(email:'jim@example.com', macros:{"name"=>"Jim", "confirmationUrl"=>"http://example.com/confirm?t=1234abcd"})
email.recipients.build(email:'amy@example.com', macros:{"name"=>"Amy", "confirmationUrl"=>"http://example.com/confirm?t=9876zyxw"})
email.recipients.build(email:'bill@example.com')
email.post
=> true

When you use an email template to create a new email message, your new email message will take on the values that are set in the template. In this case, our new email took on the subject, body, and macros values, so we did not have to specify those while creating the message. If the email template is associated with a from address the email will use properties like from email and from name set at the from address-level.

Overview

Tutorials