E-Mail Tracking¶

This functionality uses a new REST endpoint

To access the features references on this page please ensure that you are using the REST endpoints defined on this page

Introduction¶

The iovox email tracking system allows you to send emails via a REST endpoint, the delivery status of the message can be tracked as well as the any of the links present in the email have been clicked or if the images have been loaded. The system can handle attachments, both inline and attached. Emails can be sent via a proxy address which can be generated on the fly using either a shared or private domain, this allows two parties to communicate via the proxy email address so that all responses can be tracked similar to how our conversational SMS functionality works.

REST endpoints¶

The email tracking functionality is part of our new platform and as such uses different REST endpoints to our enterprise API, all functionality described on this page can only be access via the endpoints described below. You may be required to integrate with both our traditional enterprise API and the new REST API, for example creating nodes and links is on the traditional API.

While developing your integration please ensure that you use Sandbox, this environment will incur no additional costs and setup specifically to allow customers a playground to test out their integration before going live.

Environment	Endpoint
Sandbox	https://sandbox-rest.iovox.com/rest/v1
Production	https://rest.iovox.com/rest/v1

Authentication¶

The method of authentication remains the same and is common across both API endpoints, below is an example cURL request to create a pool with only the authentication headers, these same headers must be present on all requests to this endpoint.

NOTE: The authentication is not the same as what is used for the JavaScript API (accessKey), these are different to ensure full API is not part of the JavaScript snippet. This API uses the secureKey.

curl -L -X POST 'https://sandbox-rest.iovox.com/rest/v1/numbers/pool' -H 'username: CUSTOMER_USERNAME' -H 'secureKey: API_SECURE_KEY'

Requests/Responses¶

All requests and responses are in JSON, when performing a POST or PUT request the request body must be valid JSON. When performing a POST/PUT request it is possible for the REST endpoint not to return a response and the HTTP response code must be used to ensure that the request was successful.

This documentation will show the request body and the responses to each endpoint, but won't include the whole request including headers for compactness, below is a full example of a cURL requests that might be used.

curl -L -X POST 'http://sandbox-rest.iovox.com/rest/v1/numbers/pool' \
-H 'username: CUSTOMER_USERNAME' \
-H 'secureKey: API_SECURE_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"link_id": "1234", "sender_address":"bob.bob@iovox.com", "sender_name":"Bob Bob", "recipient":"bob@customer.com", "subject":"This is an email", "text_content":"This is plain text", "html_content":"<html><body>This is HTML</body></html>"}'

Validation errors¶

In the event that a request contains invalid or required fields are missing or in the wrong format, a response will be generated that contains the list of errors similar to the one below.

{
  "errors": [
    "link_id does not exist",
    "text_content cannot be empty"
  ]
}

Methods¶

This is a list of all paths and methods that are available to manage email tracking

Path	Method	Description
/rest/v1/email	POST	Send an email
/rest/v1/email/address/proxy	POST	Create new proxy address
/rest/v1/email/search	GET	Searches all emails processed using various search fields

Sending a tracked email¶

Send email fields¶

When sending an email, the fields below can be used.

Field	Required	Default	Example	Description
link_id	Yes	(N/A)	1234	`link_id` is used to associate this email with an existing link, the email will fail to send if the link doesn't already exist, it can be created via the web interface or traditional API.
sender_address	Yes	(N/A)	bob@customer.com	`sender_address` specifies the "From" address of the email
sender_name	Yes	(N/A)	Bob Bob	`sender_name` is the display name of the sender as shown in the recipients email client
recipient_address	Yes	(N/A)	bob@bob.com	`recipient_address` is the "To" address of the email
recipient_name	Yes	(N/A)	Billy Bob	The display name of the recipient of the email
subject	Yes	(N/A)	This is a subject	This the subject of the email
text_content	Yes	(N/A)	This is plain text	The plain text content of the email, this is for clients that cannot use html content and defines the plain text mime part of the message
html_content	Yes	(N/A)	<html><body>This is the html content</body></html>	The html content of the email, it defines the html mime part of the message
proxy_domain	No	(empty)	example.com	Will generate a unique email address using the specified domain, if configured for your account by our support staff, to track an email conversation by specifying this option you will enable conversational tracking of all emails using the generated email address.
proxy_name	No	(empty)	Company Name	This is the display name of the sender of the email if using conversational email tracking, if this option isn't specified, the sender_name will be used, but allows you to override the sender name for all emails sent via the tracking system when going via the proxy email address.
attachments	No	(empty)	[{attachment0},{attachment1},{attachment2}]	A JSON array of JSON objects using the field structure below

Attachment fields¶

Field	Required	Default	Example	Description
disposition	Yes	(N/A)	attachment	The MIME Content-Disposition, must be either “inline” or “attachment”. Attachment is when you want the content to show as a file in the email, inline is when you want to show an inline image or other embedded content used by the recipient email client.
type	Yes	(N/A)	application/octet-stream	Defines the MIME type of the attachment, this need to match the data of the attachment to ensure the recipients email client correctly handles this attachment.
body	Yes	(N/A)	VGhpcyBpcyBhbiBhdHRhY2htZW50	The actual content of the attachment base64 encoded.
filename	Yes if disposition = "attachment", otherwise No	(N/A)	bob.pdf	The file name displayed in the recipient's email client for the attachment.
id	Yes if disposition = "inline" otherwise No	(N/A)	bobpart0001	The MIME Content-ID used to identify the attachment when used inline for embedded images.

REST request example¶

Below is an example request to send an email, please make sure that the link_id specified in this request already exists, it can be created via the web interface or traditional API.

POST /rest/v1/email
{
  "link_id":1234,
  "sender_address":"bob.bob@iovox.com",
  "sender_name":"Bob Bob",
  "recipient_address":"bob@customer.com",
  "recipient_name":"Billy Bob",
  "proxy_domain":"example.com",
  "proxy_name":"Company Name",
  "subject":"This is an E-Mail",
  "text_content":"This is plain text",
  "html_content":"<html><body>This is HTML</body></html>"
  "attachments":[
    {"filename": "bob.txt", "disposition": "attachment", "type": "text/plain", "body":"VGhpcyBpcyBhbiBhdHRhY2htZW50"},
    {"disposition": "inline", "type": "text/plain", "id":"bobpart0001", "body":"VGhpcyBpcyBhbiBhdHRhY2htZW50"},
  ]
}

If the email has been accepted for processing, the endpoint will return a response code 201 and details that can be used for tracking the message and conversation (if requested)

{
  "message_id":"fb8fe1d0-113d-499a-83d5-58410040c67c",
  "conversation_id":"15989b40-7297-47c6-b978-fd43a4d36396",
  "proxy_address":"hn7m890cfqt234@example.com"
}

REST response fields¶

Field	Example	Description
message_id	fb8fe1d0-113d-499a-83d5-58410040c67c	The UUIDv4 ID for the email, can be used to return details about the specific message
conversation_id	15989b40-7297-47c6-b978-fd43a4d36396	The UUIDv4 ID for the conversation if one was requested, the field will be absent if the a conversation was not requested
proxy_address	hn7m890cfqt234@example.com	The generated email address if a proxy domain was specified in the request, otherwise it will be omitted in the response

Generate proxy email addresses¶

While its possible to send an email and create a new email address at the same time, this doesn't fit with the your needs so we also offer the ability to create one or more email addresses and sending of emails can be handled separately. The request is an array of objects, the fields of each object are below.

Field	Required	Default	Example	Description
link_id	Yes	(N/A)	abc1234	`link_id` is used to associate this email with an existing link, the email will fail to send if the link doesn't already exist, it can be created via the web interface or traditional API.
sender_address	Yes	(N/A)	bob@customer.com	`sender_address` specifies the "From" address of the email
recipient_address	Yes	(N/A)	bob@bob.com	`recipient_address` is the "To" address of the email
proxy_domain	Yes	(N/A)	example.com	Will generate a unique email address using the specified domain, if configured for your account by our support staff, to track an email conversation through this proxy email address that will be generated.
proxy_name	No	(empty)	Company Name	This is the display name of the sender of the email if using conversational email tracking, if this option isn't specified, the sender_name will be used, but allows you to override the sender name for all emails sent via the tracking system when going via the proxy email address.

REST request example¶

Below is an example request to generate a proxy email address, please make sure that the link_id specified in this request already exists, it can be created via the web interface or traditional API.

POST /rest/v1/email/address/proxy
[
  {
    "link_id":"abc1234",
    "sender_address":"bob.bob@[iovox.com](http://iovox.com)",
    "recipient_address":"bob@[customer.com](http://customer.com)",
    "proxy_domain":"example.com",
    "proxy_name":"Company Name"
  }
]

If the request is valid, the endpoint will return an array of objects similar to below

[
  {
    "link_id": "abc123",
    "sender_address":"bob.bob@iovox.com",
    "recipient_address":"bob@customer.com",
    "proxy_address":"hn7m890cfqt234@example.com",
    "conversation_id": "15989b40-7297-47c6-b978-fd43a4d36396"
  }
]

REST response fields¶

Field	Example	Description
link_id	abc123	The original `link_id` sent to the endpoint, this is return to help match up when multiple entries are returned
sender_address	bob.bob@iovox.com	The original `sender_address` from the request
recipient_address	bob@customer.com	The origin `recipient_address` from the request
proxy_address	hn7m890cfqt234@example.com	The generated email address if a proxy domain was specified in the request
conversation_id	15989b40-7297-47c6-b978-fd43a4d36396	The ID for the conversation that was created along with the email address, can be used to lookup emails associated to the conversation

Searching tracked emails¶

The search endpoint allows querying the all tracked emails, it will return all records matching a specified search parameters, all fields are optional, although there are some defaults if you don't specify any search parameters. As this is a GET request all search parameters must be specified in the URL.

Search fields¶

Field	Default	Example	Description
start_date	First day of the current month at midnight	2022-01-01 00:00:00	The start date/time for a ranged search based on the submission date of the email to the tracking system, the date/time format used is "YYYY-MM-DD HH:MM:SS". All dates and times are in UTC.
end_date	End of the current day one second before midnight	2022-01-31 23:59:59	The end date/time for a ranged search based on the submission date of the email to the tracking system, the date/time format used is "YYYY-MM-DD HH:MM:SS". All dates and times are in UTC.
message_id	(N/A)	fb8fe1d0-113d-499a-83d5-58410040c67c	`The message_id` returned when sending a message
node_id	(N/A)	abc123	The `node_id` to search for
node_name	(N/A)	Bobs automotive	The `node_name` to search for
node_type	(N/A)	Dealer	The `node_type` to search for
link_id	(N/A)	xyz789	The `link_id` to search for
link_name	(N/A)	Honda Civic	The ```link_name to search for
link_type	(N/A)	Vehicle	The `link_type` to search for
sender_address	(N/A)	bob@bob.com	The sender of the email as we received it
recipient_address	(N/A)	bob@customer.com	The delivery recipient of the email we transmitted
proxy_address	(N/A)	hn7m890cfqt234@example.com	The proxy address used
conversation_id	(N/A)	15989b40-7297-47c6-b978-fd43a4d36396	The conversation_id generated when sending the initial message for sending via a proxy_address
disposition	(N/A)	sent	The delivery state of the message
read_disposition	(N/A)	read	Allows searching on the whether the email has been read
fields	(see Available fields)		A comma separated list of field names to return
order	receive_date_ASC,delivery_date_DESC	receive_date_ASC,delivery_date_DESC	A comma separated list of fields to sort by
page	1	1	The page number to return when pagination is required
limit	20000	20000	The number of records to return per page

Available fields¶

This table lists all fields that are currently available, you do not need to use all fields in every request and you can just use the minimum required for your particular task. If a field does not exist on a record it will not be returned even if requested. For example its certainly possible if an email has never been read that the read_first_date will not be returned for some records, but if it exists will be returned for others.

Field	Returned by default	Type	Description
message_id	Yes	String	The `message_id` returned when sending a message
receive_date	Yes	String	The date/time we received the email for processing
delivery_date	Yes	String	The date/time we delivered the email to the destination mail server
node_id	Yes	String	The `node_id` associated with the email
node_name	Yes	String	The `node_name` associated with the email
node_type	Yes	String	The `node_type` associated with the email
link_id	Yes	String	The `link_id` associated with the email
link_name	Yes	String	The `link_name` associated with the email
link_type	Yes	String	The `link_type` associated with the email
sender_address	Yes	String	The sender of the email as we received it
sender_name	Yes	String	The display name shown "From" field of the email
recipient_address	Yes	String	The delivery recipient of the email we transmitted
recipient_name	Yes	String	The delivery recipient display name
proxy_address	Yes	String	The proxy address used
proxy_name	Yes	String	The proxy display name
conversation_id	Yes	String	The `conversation_id` generated when sending the initial message for sending via a `proxy_address`
disposition	Yes	String	The delivery state of the message
read_disposition	Yes	String	Will show if we have detected if the email as been read, will return "read" or "unread"
read_first_date	Yes	String	The date/time the message was first read

NOTE: All date/time values are returned in UTC using the format: YYYY-MM-DD HH:MM:SS

Sorting results¶

You can use any of the available fields to sort the results, to do so specify a comma separated list of fields with an _ASC or _DESC suffix as the order variable in the request.

For example, if you wanted to sort the results based on the receive_date in an ascending order you would set the query parameter "order=receive_date_ASC", you can add as many fields as you want to this list but it may take the request longer to be processed.

REST request example¶

Below is an example request to search for all email records where the link_id is abc123 for last year.

GET /rest/v1/email/search?start_date=2021-01-01%2000:00:00&end_date=2021-12-31%2023:59:59&link_id=abc123&page=1&limit=1&disposition=sent
{
  "current_page":1,
  "total_pages":5,
  "total_results":5,
  "results":\[
    {
      "message_id":"74d9a367-2784-46d7-b4a9-58149c461888",
      "receive_date":"2021-06-26 14:49:27",
      "delivery_date":"2021-06-26 14:52:40",
      "node_id":"abc123",
      "node_name":"Bobs automotive",
      "node_type":"Dealer",
      "link_id":"xyz789",
      "link_name":"Honda Civic",
      "link_type":"Vehicle",
      "sender_address":"bob@bob.com",
      "sender_name":"Bob Bob",
      "recipient_address":"[bob@customer.com](mailto:bob@customer.com)",
      "recipient_name":"Billy Bob",
      "proxy_address":"[hn7m890cfqt234@example.com](mailto:hn7m890cfqt234@example.com)",
      "proxy_name":"Company Name",
      "disposition":"sent",
      "read_disposition":"unread"
    }
  \]
}

Returned results¶

The JSON object returned has the fields show in the table below, the actual results are contained in the results field.

Field	Description	Type	Example
current_page	The current result page for pagination	Long	1
total_pages	Based on the limit, how many pages are left to get all results in the query	Long	5
total_results	How many records were returned in this call	Long	5
results	The actual results returned for the query	Array of JSON objects	(See available fields above)

Dispositions¶

Just like phone calls the email tracking system can have many dispositions, below is a list of all the disposition states that can be returned and what they mean.

Disposition	Meaning
noMxRecord	There is no MX record for the delivery domain in DNS, unable to deliver and will not retry
sent	The remote SMTP server has accepted the message for delivery
undeliverable	The remote SMTP server has returned a permanent (500+) error message and we will not retry delivery
queued	The message failed to be sent, but we will queue the message and try again
no_rules	No rules have been configured to process this message, the message will not be sent
rule_error	There was an error processing the rules for this message, the message will not be sent
received	We have received the message and it is currently being processed
received_bounced	We sent the message successfully but we received a bounce message
expired	The message was queued for delivery, but after many attempts we failed to deliver it, we will not attempt delivery again

Read Dispositions¶

Whether the email has been read or not, by default email sent are in the unread state, in the event the web-bug is loaded or a link is clicked then the read_disposition is changed to read.

Disposition	Meaning
unread	Email hasn’t had the web bug loaded or a tracked link clicked
read	The Email has had one of the tracking methods tripped