This API will allow for the retrieval of tracking data for various tracking data types. The API is designed such that data is streamed back in batches from a given ID or date/time.

Authentication

Every HTTP request to the web service must be authenticated; in order to do so, every request must include three HTTP headers: Authorization, Content-Type, & Date. The Date header must match the current date and time, and requests with dates too far in the future or past will be rejected. If you do not have control over the Date header, instead include the X-RealMagnet-Date header, which will be used in preference to the Date header. The Date header must be formatted as specified in the Date Format section of this document.

The Authorization header will have the following form:

Authorization: RealMagnet MailUserID:Signature

The MailUserID will be assigned to your account by Higher Logic Thrive Marketing Enterprise (Thrive Marketing Enterprise), along with an APISecretKey. The Signature is computed by taking the HMAC-SHA1 of a specially constructed string, using the APISecretKey as the key. The following is a sample C# code to compute this signature:

var apiSecretKey = "wgn1zeQU0ybgkmPbu7gAuTnyniyEfE61VDd57Kwksw";
var http_method = "POST";
var http_contentMd5 = "15b3d3e87c1c8032fae05e5235af1206";
var http_contentType = "application/json;charset=utf-8";
var http_date = "Thu, 06 Dec 2012 16:56:13 GMT";
var http_customHeaders = ...
var http_requestUrl = "https://api105.magnetmail.net/v5/rest/upload-and-send/";
var action = "";
var stringToSign = string.Format("{0}\n{1}\n{2}\n{3}\n{4}\n{5}\n{6}",
       http_method.ToUpperInvariant(), http_contentMd5, http_contentType, http_date, http_customHeaders,
       http_requestUrl, action);
var encoding = new UTF8Encoding(false);
var keyBytes = encoding.GetBytes(apiSecretKey);
var messageBytes = encoding.GetBytes(stringToSign);
var hmac = new HMACSHA1(keyBytes);
var hash = hmac.ComputeHash(messageBytes);
var signature = Convert.ToBase64String(hash);
return signature;

The value of http_customHeaders in the above sample is computed by concatenating, separated by newlines, the normalized form of all HTTP headers beginning with “X-RealMagnet-“. Headers are normalized by the following procedure:

1. Only headers with name beginning with “X-RealMagnet-“ are included.
2. Header name is converted to lower case.
3. Header names are sorted lexographically.
4. Headers with multiple values are converted into a header with a single value that is a comma separated list (with no space preceding or trailing the comma); order must be maintained.
5. Newlines are removed from header values.
6. Header name is concatenated with header value, separated by a colon “:” (with no space between the header name and the colon, or between the colon and the header value).
7. All header name/value pairs are concatenated into a single string, with a single newline between each pair and no additional space preceding or trailing the newline.

Important points to note:

• The HTTP Method is converted to all uppercase when computing the signature
• The Content-Type and Date headers are included exactly as is in the HTTP request.
• The request URL in the example above is for the RESTful endpoint.
• A request to a SOAP endpoint will include the soap action when computing the signature.
• A request to a REST endpoint will include an empty (blank) action when computing the signature.
• The encoding must not add a BOM before computing the signature; hence, var encoding = new UTF8Encoding(false); is used.

Operations

UpdateTrackingStreamState

Description

This call will ‘initialize’ the tracking data stream with ID / dates that dictates where record retrieval begins. As data is streamed down the API will automatically advance to the next set of relevant records.

URL

PUT https://api105.magnetmail.net/v5/rest/tracking/{tracking-type}

Content parameters

Name	Type	Value Range	Description
tracking-type	String (part of url)	Refer to Tracking types	Must be a valid/supported tracking type

JSON body content

{
  “starting-id”: 903123
  “starting-date”: “03/30/1999”
}

Content parameters

Name	Type	Value Range	Description
starting-id	long	Valid long values	ID value of tracking records to stream down
starting-date	DateTime	mm/dd/yyyy date values	Starting date for record retrieval

Response object

Name	Type	Description
next-start-id	long	Starting ID determined from request input
Messages	DiagnosticMessage collection	Informational, warning, and error messages. If the upload request is not valid, these messages explain why

Example request

PUT /v5/rest/tracking/email-open HTTP/1.1
Date: Mon, 30 Jun 2014 17:47:45 GMT
Content-Type: application/json;charset=utf-8
Authorization: RealMagnet YourAccount:ygQQ9IUZZukpXgpwSZaLRsF/2NA=
Host: api105.magnetmail.net

{
   “starting-date”: “04/15/2008”
}

OR

{
   “starting-id”: 3829132
}

Constraints

This call is subject to the following constraints:

• All parameters must match the value ranges as specified in this document.
• A starting ID or Date must be provided.
• If both are provided, ID will take precedence.

GetTrackingDataInRange

Description

This call will retrieve records from a specified starting point but will not modify the current stream tracking state.

URL

GET https://api105.magnetmail.net/v5/rest/tracking/{tracking-type}?{parameters}

URL parameters

Name	Type	Value Range	Description
tracking-type	String	Refer to Tracking types	Must be a valid/supported tracking type
start_id	long	Valid long	The ID to start pulling data from
start_date	date	date	The date to start pulling data from
end_date	date	Valid date	The date to stop pulling data at
max_rows	int	Valid integer with a value less or equal to 2000	Total number of rows that can be returned
fields	string[]	Valid strings that map to field value or empty	Fields to retrieve. If not provided, all fields are returned.

Response object

Name	Type	Description
next-start-id	long	Starting ID determined from request input.
fields	string[]	A listing of the fields returned.
Data	object[][]	All data values for the result set.
HasMore	bool	Details if there are more records to be retrieved.

Example request

GET /v5/rest/tracking/email-open?start-id=123122&max_rows=500 HTTP/1.1
Date: Mon, 30 Jun 2014 17:47:45 GMT
Content-Type: application/json;charset=utf-8
Authorization: RealMagnet YourAccount:ygQQ9IUZZukpXgpwSZaLRsF/2NA=
Host: api105.magnetmail.net

Constraints

This call is subject to the following constraints:

• All parameters must match the value ranges as specified in this document.

StreamTrackingData

Description

This call will retrieve the next batch of unread tracking records and return them. This call will advance the stream state so subsequent calls continue to fetch unread records.

URL

GET https://api105.magnetmail.net/v5/rest/tracking/{tracking-type}/next?{parameters}

URL parameters

Name	Type	Value Range	Description
tracking-type	String	Refer to Tracking types	Must be a valid/supported tracking type
max_rows	int	Valid integer with a value less or equal to 2000	Total number of rows that can be returned
fields	string[]	Valid strings that map to field value or empty	Fields to retrieve. If not provided, all fields are returned.

Response object

Name	Type	Description
next-start-id	long	Starting ID determined from request input.
fields	string[]	A listing of the fields returned.
Data	object[][]	All data values for the result set.
HasMore	bool	Details if there are more records to be retrieved.

Example request

GET /v5/rest/tracking/email-open/next?start-id=123122&max_rows=500 HTTP/1.1
Date: Mon, 30 Jun 2014 17:47:45 GMT
Content-Type: application/json;charset=utf-8
Authorization: RealMagnet YourAccount:ygQQ9IUZZukpXgpwSZaLRsF/2NA=
Host: api105.magnetmail.net

Constraints

This call is subject to the following constraints:

• All parameters must match the value ranges as specified in this document.

Tracking types

Below is a list of all supported tracking types:

• link-click
• email-open
• email-send
• Email-send-status
• event-signup
• Fax
• sms-send
• subscribe
• survey-submission
• social
• unsubscribe
• Google-analytics-links
• Suppressed
• Groups
• Groups-updated
• Messages
• Messages-sent
• Email-message-groups

Date format

The date and time specified in the HTTP Date header (or the X-RealMagnet-Date header, if specified), should match the format described by the grammar below (based on RFC 1123 and HTTP/1.1):

full-date     = day-name "," SP date SP time SP "GMT"
date          = 2DIGIT SP month SP 4DIGIT
                ; day month year (e.g. 02 Jan 2012)
time          = 2DIGIT ":" 2DIGIT ":" 2DIGIT
                ; hours minutes seconds, 24-hour format (e.g. 23:59:59)
day-name      = "Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat"
month         = "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun"
              | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec"
DIGIT         = <any single digit, 0 - 9>
SP            = <ASCII 32, the space character>

For the purposes of this API, midnight is considered the first second of the day; that is, “Mon, 02 Jan 2012 00:00:00 GMT” is preceded by “Sun, 01 Jan 2012 23:59:59 GMT” and followed by “Mon, 02 Jan 2012 00:00:01 GMT”.

Additional resources