This API allows you to submit a one-time file upload job in conjunction with MagnetMail File Integration. In order to do this, MagnetMail File Integration must be enabled for your Higher Logic Thrive Marketing Enterprise (Thrive Marketing Enterprise) account.

NOTE: This API does not transfer files to Thrive Marketing Enterprise; that step must be performed separately.

The general workflow is:

1. Upload a file to your MagnetMail File Integration FTP site.
2. Use the UploadFile API operation to run a one-time upload that will import the data from the file used in step 1 into the selected MagnetMail group.
3. Use the GetJobStatus API operation to determine if the upload job created in step 2 has completed.

Authentication

Every HTTP request to the web service must include the following three headers in order to must be authenticated.

• 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 article.

The Authorization header will have the following form:

Authorization: RealMagnet MailUserID:Signature

The MailUserID will be assigned to your account by 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 = "http://www.example.org/v5/rest/file-uploads/";
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 above 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 lexicographically.
4. Headers with multiple values are converted into a header with a single value that is a comma-separated list (with no space preceding 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 colon or between the colon and 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 notes

• The HTTP Method is converted to 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 an UploadFile operation, using 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

UploadFile

Description

After a file has uploaded to your FTP local, this operation allows you to initiate the job of transferring data from the file into your MagnetMail contacts.

NOTE: Unless otherwise indicated, all job parameters are required.

Parameters

Name	Type	Description
FieldMapping	FieldMappingCollection	Describes the mapping of file columns to MagnetMail recipient fields.
FilePath	String	The path of the file to upload, relative to your FTP location.
Groups	GroupDescriptor collection	Detailed information about the group or groups this upload is targeting.
UploadOptions	UploadOptions	Additional, optional job parameters

Response object

Name	Type	Description
JobID	Integer (64 bit)	The identifier of the job, to be used with the GetJobStatus operation. This will be omitted if the upload request is not valid.
Messages	DiagnosticMessage collection	Informational, warning, and error messages. If the upload request is not valid, these messages will explain why.

Constraints

In order to use this API, your MagnetMail account must be configured for File Upload Integration. All parameters must match the value ranges as specified in this document. Additional constraints are determined by the MappingType of the FieldMapping parameter:

ByName

• Each mapping entry must contain a MagnetMailFieldName.
• Each mapping entry must contain a FileColumnName.
• The FileOrdinal property is ignored.
• Exactly one mapping entry must specify a MagnetMailFieldName of “custom_memberid”.
• Null mapping entries are not allowed.
• The first non-skipped line in the file must specify the column names; i.e. you must not skip the header line.
• The column which is mapped to the specified MagnetMailFieldName is determined by matching the specified FileColumnName to the column name in the header line.

ByOrdinal

• Each mapping entry must contain a MagnetMailFieldName.
• Each mapping entry must contain a FileOrdinal.
• The FileColumnName property is ignored.
• Exactly one mapping entry must specify a MagnetMailFieldName of “custom_memberid”.
• Null mapping entries are not allowed.
• The first non-skipped line in the file must be the first data line; i.e. you must skip the header line.
• The column which is mapped to the specified MagnetMailFieldName is determined by matching the specified FileOrdinal to the position of the column in the file.

ByPosition

• Each non-null mapping entry must contain a MagnetMailFieldName.
• The FileOrdinal property is ignored.
• The FileColumnName property is ignored.
• Exactly one mapping entry must specify a MagnetMailFieldName of “custom_memberid”.
• Null mapping entries are allowed, and indicate skipped columns.
• The first non-skipped line in the file must be the first data line; i.e. you must skip the header line.
• The column which is mapped to the specified MagnetMailFieldName is determined by matching the position of the entry in the collection to the psotion of the column in the file.

Additional constraints are determined by the UseSampling option of the UploadOptions parameter:

If UseSampling is TRUE

• You may specify multiple groups by specifying multiple group descriptors; at least one group descriptor is required.
• Each group descriptor must specify a sample size between 1 and 100, inclusive; this will be interpreted as a percentage.
• The sum of all sample sizes must be less than or equal to 100.

If UseSampling is FALSE

• You must specify exactly one group descriptor.
• Sample size will be ignored.

Additional constraints are determined by the UseTemporaryGroups option of the UploadOptions parameter:

If UseTemporaryGroups is TRUE

• The group names specified in the group descriptors must not match the name of existing groups.
• The groups will be created as temporary groups.
• AddOrReplaceGroupMembers is ignored for all groups.

If UseTemporaryGroups is FALSE

• Each group named in a group descriptor will be created or updated as necessary.
• If a group name matches an existing group, that group must not be a temporary group.
• The AddOrReplaceGroupMembers option is ignored for new groups.

SOAP endpoint

The SOAP endpoint is located at http://api105.magnetmail.net/v5/soap/file-uploads/.

The action for this operation is
http://xmlns.realmagnet.com/magnetmail-api-service/v5/actions/IFileUploadContract/UploadFile.

NOTE: For a sample SOAP request, refer to Additional resources at the bottom of this article.

REST endpoint

The REST endpoint is located at http://api105.magnetmail.net/v5/rest/file-uploads/.

It uses the POST HTTP method. A sample JSON REST request is below.

POST http://api105.magnetmail.net/v5/rest/file-uploads/ HTTP/1.1
User-Agent: Mozilla/5.0 (compatible; Windows NT 6.1)
Accept-Charset: utf-8
Content-Type: application/json;charset=utf-8
Accept: application/json;text/javascript
Date: Mon, 02 Jan 2012 11:12:13 GMT
Authorization: RealMagnet Mitch:EGIj5u9wN/vE1opSmWR38JkCGsE=
Content-Length: 388
Host: api105.magnetmail.net

{
         "FieldMapping":{
                 "MappingType":"ByPosition",
                 "Mappings":[{"MagnetMailFieldName":"custom_memberid"}]
                 },
         "FilePath":"Telephone List.csv",
         "Groups":[{
                 "Name":"My Upload Group",
                 "SampleSize":25
                 }],"UploadOptions":{
                 "CategoryName":"Category",
                 "Delimiter":",",
                 "Quote":"\"",
                 "SkipLines":"8",
                 "UseTemporaryGroups":true,
                 "UseSampling":true
                 }
}

GetStatus

Description

Retreives the status of a file upload job.

Parameters

Name	Type	Value Range	Description
JobID	String	Must be a valid string representation of a 64-bit integer.	The JobID returned from a previous call to UploadFile

Response object

Name	Type	Value Range	Description
StatusCode	String	NotFound, NeverRun, Queued, Running, Success, Failed	The overall status of the upload job.
Messages	DiagnosticMessage collection		Informational, warning, and error messages related to the processing of the specified job.

SOAP endpoint

The SOAP endpoint is located at http://api105.magnetmail.net/v5/soap/file-uploads/.

The action for this operation is
http://xmlns.realmagnet.com/magnetmail-api-service/v5/actions/IFileUploadContract/UploadFile.

A sample SOAP request for the status of JobID 12345 is below:

POST http://api105.magnetmail.net/v5/soap/file-uploads/ HTTP/1.1
Connection: close
Accept-Encoding: gzip,deflate
Content-Type: application/soap+xml;charset=UTF-8;action=
"http://xmlns.realmagnet.com/magnetmail-apiservice/v5/actions/IFileUploadContract/GetStatus"
Authorization: RealMagnet Mitch:43LdBAXgBb6jqSKA1sv/sxMNltk=
Date: Mon, 02 Jan 2012 11:12:13 GMT
Content-Length: 536
Host: api105.magnetmail.net
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:act="http://xmlns.realmagnet.com/magnetmail-api-service/v5/actions">
   <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <wsa:Action>http://xmlns.realmagnet.com/magnetmailapi-service/v5/actions/IFileUploadContract/GetStatus
   </wsa:Action><wsa:To>
   http://api105.magnetmail.net/v5/soap/fileuploads/</wsa:To></soap:Header>
   <soap:Body>
      <act:GetStatus>
         <act:jobID>12345</act:jobID>
      </act:GetStatus>
   </soap:Body>
</soap:Envelope>

REST endpoint

The REST endpoint is located at http://api105.magnetmail.net/v5/rest/file-uploads/{JobID}/status, and uses the GET HTTP method.

In this URL, the token {JobID} must be replaced with the actual value of the JobID parameter.

A sample JSON REST request for the status of JobID 12345 is below.

GET http://api105.magnetmail.net/v5/rest/file-uploads/12345/status HTTP/1.1
User-Agent: Mozilla/5.0 (compatible; Windows NT 6.1)
Accept-Charset: utf-8
Content-Type: application/json;charset=utf-8
Accept: application/json;text/javascriptDate: Mon, 02 Jan 2012 11:12:13 GMT
Authorization: RealMagnet Mitch:mS8XoeuVL2pBeYQidFpE50rb0AE=
Host: api105.magnetmail.net

Object reference

GroupDescriptor

NOTE: AddOrReplaceGroupMembers and UpdateRecipients are optional parameters. If omitted, the configured default will be used.

Name	Type	Value Range	Description
Name	String	Unicode code points U+0020 through U+007E (printable Basic Latin w/ space)	Uploaded recipients will be added to the named group.
SampleSize	Integer (32 bit)	1 through 100, inclusive	The percentage of total good records to place in this group.
AddOrReplaceGroupMembers	String	Add or Replace	Add - New recipients will be added to the group and existing members will be retained. Replace - All members will be removed from the group before recipients are added.
UpdateRecipients	String	KeepExistingRecipientData UpdateRecipientData	Regardless of this option, recipients that are newly added to the MagnetMail system during this upload job will have their fields set according to the specified mapping. KeepExistingRecipientData - the recipient data for existing MagnetMail recipients will not be altered. UpdateRecipientData - the recipient data for existing MagnetMail recipients will be updated by the file data.

FieldMappingCollection

Name	Type	Value Range	Description
MappingType	String	ByName ByOrdinal ByPosition	Specify how items in the Mappings collection are matched to columns in the file.
Mappings	FieldMapping collection		Each item in this collection specifies how a single column is mapped.

FieldMapping

NOTE: FileColumnName and FileOrdinal are optional parameters.

Name	Type	Value Range	Description
MagnetMailFieldName	String	Any MagnetMail recipient field name	The name of the field / property of the MagnetMail recipient to update.
FileColumnName	String		The column name as it appears in the column header.
FileOrdinal	Integer (32 bit)	Non-negative	The position of the column in the file; the first column is column 1.

UploadOptions

NOTE: All of the following parameters are optional.

Name	Type	Value Range	Description
CategoryName	String	Unicode code points U+0020 through U+007E (printable Basic Latin w/space)	If specified, a new group will be added to this Category. If not specified, no action is taken.
Delimiter	String	Any single character	The character used to separate columns in the file. The default is ,.
Filter	String	Any valid filter expression	If specified, only rows matching the filter will be included in the upload.
FooterStartLine	String		If specified, when a line exactly matching this option is encountered in the file, the start of the footer is assumed and processing of file data will stop. If omitted, data is processed to the end of the file.
Quote	String	Any single character	The character used to escape text strings. The default is ".
SkipLines	Integer (32 bit)	Non-negative	The number of lines to skip at the start of the file before processing data. The default is 0.
UseSampling	Boolean		If true, multiple groups may be specified, with each group receiving a portion of the uploaded recipients. The default is false.
UseTemporaryGroups	Boolean		If true, the groups specified by the group descriptors are temporary groups. The default is false.
UseUtf16Encoding	Boolean		If true, the file will be interpreted as if it is encoded with UTF-16 LE. The default is false.

Date format

The date and time that are specified in the HTTP Date header (or the X-RealMagnet-Date header, if specified), should match the format described by the example 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