Deliverability and Reporting

TMS provides several deliverability and reporting features, so you can track what happens to the messages you send.

Deliverability shows the status of an individual message, following its path to the recipient’s mailbox.

Reporting dives deeper into what happens to a message once received. TMS will show whether a message was opened or left unread, and whether the recipient clicked on any links.

Webhooks (also called web callbacks or HTTP push API) can be configured to alert your application when specific delivery event type occurs.

Together, you can use these features to quantify behavior and highlight patterns to inform how your application behaves, or how messages are crafted and targeted in the future. Better data means better decisions for your digital communications strategy.

What’s in this section

Deliverability	Reporting	Webhooks
1. Deliverability overview	1. Reporting overview	1. Webhooks overview
2. Message status	2. Getting report data	2. Enabling webhooks
		3. Common errors and handling

Deliverability

Once a message is sent, it passes through various stages of an Internet Service Provider (ISP) system to get to the recipient inbox. For many messages, the ISP system can keep an email from ever making it to the inbox. For government organizations with information that is critical and timely, reliable deliverability is essential.

GovDelivery is trusted by over 1,800 government agencies to send billions of messages every year. Of those billions of messages, 98% arrive in citizens’ inboxes.

Deliverability metrics reflect the number of messages that reached inboxes of the total number sent. Deliverability can also suggest why a message doesn’t make it through the system. For troubleshooting information, see Common Errors and Handling.

Message Status

Message status reflects where an email message is in the process of sending an email. As your messages make their way through the sending and ISP systems, you can check status using the TMS API.

See the table below for status messages and their meaning.

Status	Impact
New	The message hasn’t been sent to the recipient yet.

Sending	The message was sent to the recipient, but the deliverability is unknown.

Sent	The message was sent to the recipient and is confirmed as delivered.

Failed	The message was sent to the recipient and is confirmed as failed.

Inconclusive	The message was sent to the recipient, but the system hasn’t responded with a “sent” or “failed” message. We count this as a failure to deliver.

Retrieve the status of multiple messages by submitting a GET request to https://tms.govdelivery.com/messages/email
Retrieve the status of single message (along with message content and recipient status rollup counts for the message) by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}

Reporting

Once a message is delivered to an inbox, the recipient may it treat it in a number of ways. Reporting metrics dive deeper into what happens to a message once it’s received. TMS will show whether a message was opened or left unread, and whether the recipient clicked on any links. These metrics are straightforward to use, and can provide insight on how recipients engage with your messages.

TMS captures message metadata and generates reports that can inform your digital communications strategy. Report data supports data-driven decisions by quantifying behavior and highlighting patterns within a large sample.

All requests to TMS will result in a response payload for that message which includes a message ID. This ID can be considered the primary key for the message and should be captured and held within your application database. The message ID is required for any future interactions with TMS to get reporting data on that message.

There are two ways to utilize TMS report data: Getting report data and webhooks.

Getting report data. Getting reports provides data in a comprehensive collection of data collected over a period of time generated by your organization.

Report data is retrieved by using HTTP GET request, a standard call for REST APIs. These report data are retrieved when the agency application initiates a call which includes the message ID.

Webhooks. Reports are complemented by webhooks. Instead of a full report, webhooks provide specific, near-real-time notifications about the messages you send. Webhooks are timely and act as alerts when configured, so that your application does not need to initiate a call to get a specific data point such as “failed” message.
Use both reports and webhooks together to most effectively leverage TMS report data. Keep reading below for more details on report data and webhooks.

Getting report data

Report data is retrieved by using HTTP GET method, a standard call for REST APIs. These report data are retrieved when the agency application initiates a call.

HTTP methods are simple and effective. These API calls are straightforward because it’s a single input for an output. This approach for getting report data is generated as-needed for specific scenarios.

TMS is a REST API that receives and responds to what are called “requests”. The standard technical format for requesting data from a REST API is HTTP methods. These methods reflect a type of action. For example, the HTTP method “GET” is a request to receive data from TMS.

The GET method is used when retrieving report data from TMS. Send a simple “GET” request to the matching TMS endpoint, and TMS will respond with the data in a JSON data format.

The table below outlines the possible report data that you can request from TMS and the endpoints for each.

Report Data	Endpoint
Get list of recipients	/messages/email/{messageID}/recipients

Get failed messages	/messages/email/{messageID}/recipients/failed

Get list of recipients sent to	/messages/email/{messageID}/recipients/sent

Get clicked data (web links)	/messages/email/{messageID}/recipients/clicked

Get opened messages	/messages/email/{messageID}/recipients/opened

Retreive the status of all recipients for a message by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}/recipients
Retrieve the status of all recipients with a status of failed for a message by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}/recipients/failed
Retrieve the status of all recipients with a status of sent for a message by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}/recipients/sent
Retrieve the status of all recipients who clicked a link in a message by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}/recipients/clicked
Retrieve the status of all recipients who opened a message by submitting a GET request to https://tms.govdelivery.com/messages/email/{email_id}/recipients/opened

Webhooks

Webhooks complement report data by providing specific, near-real-time data about messages. As a message moves through the sending and ISP process, it goes through a number of “events”. These events are recorded as data points in the report data, and they can also trigger a webhook to push the information as the event happens.
Webhooks may be enabled for these event types:

sending
sent
canceled
blacklisted (marked as spam or unsubscribed)
failed (did not reach inbox)
inconclusive (counted as a failure)

Here’s how it works if you are interested in ‘failed’ email messages:

A message is sent to the ISP for delivery. If the email address does not exist, the ISP will sent a “permanent failure” message back to TMS – this is a hard bounce.
The event for the message is recorded as “failed”, and it triggers the enabled webhook.
The webhook automatically pushes the TMS event data in near-real-time to your service URL (must be separately configured) with a POST request.
The data is captured and handled according to how your service is configured.
Remove recipient email address from your system.

Before you start

Set up a service. Before you can set alerts with TMS, you’ll need to separately set up a service that receives and handles the TMS data submitted by the enabled webhook. Your service should be able to receive the POST request from TMS as well as move the data to your internal database to intake and process.

Set up the callback URL. Once you’ve set up the service, it must be exposed through a URL in order to receive the HTTP request. The URL serves as the callback URL to which the POST request is sent.

Enabling webhooks

Setting alerts by enabling webhooks is a two-step process: defining + enabling and accepting.

Define the event type and enable the webhook. A webhook is associated with a single event type (any of the event types listed above).

Once you’ve chosen the event type for the webhook, enable the webhook by submitting a POST request to https://tms.govdelivery.com/webhooks with the following request payload. In this case we are using RequestBin to accept the webhook.
```
 {
   "url": "http://requestb.in/qc4vbrqc",
   "event_type": "failed"
 }
```
In general, the URL value is your callback URL and the event type states one of the event types listed above. In this example, the pre-defined event type is “failed”.

The below is the FORM POST data for event type of failed.
```
 status: failed
 error_message: "550 5.1.1 5.1.1 The email account that you tried to reach does not exist. Please try 5.1.1 double-checking the recipient's email address for typos or 5.1.1 unnecessary spaces. Learn more at  https://support.google.com/mail/answer/6596 e193si4044854ioe.131 - gsmtp"
 recipient_url: https://stage-tms.govdelivery.com/messages/email/8067770/recipients/8549216
 message_url: https://stage-tms.govdelivery.com/messages/email/8067770
 message_type: email
 completed_at: 2015-09-25 15:48:06 UTC
 sid: e54acb0f3c30b834fff4c0c1e3a4b801
```
Once your webhook is enabled, you can get alerts about the messages you send.
Accept webhook data. Webhooks automatically submit a POST request to your service with TMS data when triggered by an event. Once the data is sent to your service URL, the data must be captured and processed. How your service handles data is defined during initial setup, and varies from agency to agency. As a baseline, the TMS data pushed by the webhook is best captured and processed in your internal database.

Common errors and handling

The following table outlines the common HTTP status codes.

Status Code	Description	Meaning
100	Continue	This could be indicative of a couple of things. Too many redirections could show some inefficiency internal to the web app design. It may also show some form of load balancing was being used.
200	OK	Standard response for successful HTTP request. This is what engineers want to see in web communications.
3xx	Redirection	This could be indicative of a couple of things. Too many redirections could show some inefficiency internal to the web app design. It may also show some form of load balancing was being used.
401	Unauthorized	Authentication either failed or was not provided.
403	Forbidden	Client issue of application making an illegal request. Server is refusing to respond.
404	Not Found	Requested resource was not found. Subsequent requests from client permissible.
500	Internal Server Error	Generic error for when server failed to fulfill a request.
502	Bad Gateway	Server was acting as a gateway or proxy, and received invalid response from upstream server.
503	Service Unavailable	Server currently unavailable; either overloaded or temporarily down. If server is under high memory pressure, it will temporarily refuse new requests. If this error code persists, server may need additional memory or memory configuration settings may need to be changed.

Overview

Tutorials

Reference

Download API Descriptor