Email Deployment Lookup

Summary

The Deployment Lookup API provides the ability to retrieve deployment information such as link tracking, delivery statistics, deployment status, history, etc. via an HTTP GET request.

Base Resource URI

For Production, use: 
https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/omail/deployment/lookup/{trackId}/*

For Testing, use: 
https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/omail/deployment/lookup/{trackId}/*

brandAbbreviation is the abbreviation for the brand to which the data is being posted. trackId is the unique identifier for the deployment being requested.

Technical Requirements

The HTTP header must contain the following elements: x-omeda-appid a unique id provided to you by Omeda to access your data. The request will fail without a valid id. content-type a content type supported by this resource. See Supported Content Types for more details. If omitted, the default content type is application/json.

Supported Content Types

If omitted, the default content type is application/json. JSON application/json

JSON is the preferred data exchange format, because it is lightweight and, in most cases, faster to process and utilizes less bandwidth. There are many available open-source JSON libraries available. See json.org for details.

Supported HTTP Methods

There is one HTTP method supported: GET See W3C’s GET specs for details.

GET method is used when retrieving deployment information

Field Definition

The following tables describe the hierarchical data elements.

Lookup Elements

Attribute Name	Required?	Data Type	Description

Attribute Name	Required?	Data Type	Description
SentCount	required	integer	Number of emails that have been successfully sent to email inboxes.
SentDate	condition	date	If the deployment has been sent, the date the deployment was sent. Example: ‘2012-04-23 15:10:11’ (Central Standard Time)
DeploymentName	required	string	The user-entered name of the deployment, designated when the deployment was created.
UniqueOpens	required	integer	The number of unique email accounts that opened this deployment.
SplitCount	required	integer	The number of splits for this deployment.
BounceCount	required	integer	The number of emails that were not accepted into recipient email inboxes after the 72-hour retry period.
ApprovalDate	required	date	The date the deployment was approved for scheduling. For Omail API generated deployments, this date will be the date that the user made the Deployment Schedule API call. An example: ‘2012-04-23 08:58:55’ (Central Standard Time).
UniqueClicks	required	integer	The number of unique email addresses that clicked on this deployment.
RetryCount	required	integer	The number of email addresses that are currently in retry status. Emails that ‘bounce’ (are not accepted by the recipients ISP) will be retried for a 72 hour period.
Splits	required	array	Split information for the deployment. Each deployment can have one or many splits, each of which has its own email information such as Subject, From, Html content, and Text content. Please see ‘Splits Element’ table below.
TotalOpens	required	integer	The total number of email inboxes that opened the deployment
OwnerUserId	required	string	The Omail account userId that is authorized to edit the deployment.
SendingCount	required	integer	The number of emails that are currently in ‘sending’ status. They are in the process of being delivered.
FinalApproverUserId	required	date	The Final Approver for the deployment. This is specified when the deployment is created.
TrackLinks	required	string	true / false
LinkTracking	optional	array	An array of objects that hold a list of the links that were tracked with total click counts and unique click counts etc. Please see the ‘LinkTracking Elements’ below for a list of fields
CampaignId	optional	string	The Campaign Id specified when the deployment was created, an empty string if none was specified.
ScheduledDate	required	date	The date the deployment has been scheduled to send.
RequestedDate	required	date	The date the deployment has been originally requested to be sent
TrackOpens	required	string	true/false
Notes	optional	string	Optional user-specified text that is set when the deployment is created.
Status	required	string	The current status of the deployment. Valid values are : ‘Cancelled’, ‘New’, ‘Sending’,’Scheduled’,’Sent’,’Waiting Review’,’Not Accepted’,’Accepted’,’Submitted’, and ‘Approved’.
TotalClicks	required	integer	Total number of clicks registered for this deployment.
TrackId	required	string	The tracking number used to identify the deployment.
CreatedBy	required	string	The Omail account UserId or service that created the deployment.
CreatedDate	required	date	The date the deployment was created.
RecipientCount	required	integer	The number of recipients being deployed to.
IsFiltered	required	string	true/false
ModificationHistory	required	array	An array of objects that hold information regarding changes that have been made to the deployment.
Testers	optional	array	An array of json objects. Each object contains deployment tester information: First Name, Last Name, and Email Address.
DeploymentTypeId	required	integer	The Deployment Type Identifier in the Omail system. The Cross Reference API can be used to see all available deployment types for a given brand.
DeploymentTypeDescription	required	string	The Deployment Type description in the Omail system. The Cross Reference API can be used to see all available deployment types for a given brand.
DeploymentDesignation	required	string	The deployment designation.
ReloadOnqQueryBeforeFinalDeployment	required	boolean	Whether the deployment is set to re-execute an assigned OnQ query, when applicable.
BillingCategoryCode	optional	string	8 characters billing category if assigned to deployment

Splits Elements

Attribute Name	Required?	Data Type	Description

Attribute Name	Required?	Data Type	Description
FromEmail	required	string	The ‘From’ email address, specified when the deployment content was created.
TextSpamScore	required	double	The SpamAssassin spam score calculated for the deployment text content. Example: ‘1.2’. Value will be 0.0 if no text content is present.
Subject	required	string	The subject of the email, specified when the deployment content was created.
FromName	required	string	The ‘From’ name, specified when the deployment content was created.
RecipientList	conditional	string	The name of the recipient file used when the deployment was created.
QueryName	conditional	string	The name of the OnQ query used for the deployment.
OutputCriteria	conditional	string	The name of the OnQ output criteria used when using an OnQ query for the deployment audience, otherwise ‘Default’.
HtmlSpamScore	required	double	The SpamAssassin spam score calculated for the deployment Html content. Example: ‘1.2’. Value will be 0.0 if no Html content is present.
Sequence	required	integer	The split number: 1, 2, etc… depending on how many splits the deployment has.
HtmlContentUrl	required	link	A url to retrieve the html content for the given deployment. Format : http://ows.omeda.com/webservice/rest/brand/{brandAbbreviation}/omail/deployment/content/lookup/html/{trackId}/1/* .
TextContentUrl	required	link	A url to retrieve the text content for the given deployment. Format : http://ows.omeda.com/webservice/rest/brand/{brandAbbreviation}/omail/deployment/content/lookup/text/{trackId}/1/* .

LinkTracking Elements

Attribute Name	Required?	Data Type	Description

Attribute Name	Required?	Data Type	Description
Category	optional	string	The category of the link
CategoryValue	optional	string	Description value for the link category
Keywords	optional	array	String array of keywords for the link
LinkName	optional	string	Name of the link
LinkTag	optional	string	Tag name of the link
LinkUrl	required	string	Url of the link
MessageType	required	string	HTML or TEXT, indicating which message body type the link belongs to
Tracked	required	integer	0 = not tracked, 1 = tracked
WebTracking	required	integer	0 = web tracking off, 1 = web tracking on
UniqueClickCount	optional	integer	Number of total unique clicks for the link
ClickCount	optional	integer	Number of total clicks for the link

ModificationHistory Elements

Attribute Name	Required?	Data Type	Description

Attribute Name	Required?	Data Type	Description
ChangeDescription	required	string	The description of the change made.
ChangedBy	required	string	The Omail account UserId that made the change.
ChangedDate	required	date	The date the change was made.

Testers Elements

Attribute Name	Required?	Data Type	Description

Attribute Name	Required?	Data Type	Description
FirstName	required	string	The first name of the tester.
LastName	required	string	The last name of the tester.
EmailAddress	required	string	The email address of the tester.

GET JSON Request Example

{
    "SentCount": 642,
    "SentDate": "2012-04-23 15:10:11",
    "UniqueOpens": 5,
    "DeploymentName": "FOO Deployment #3 - April",
    "SplitCount": 1,
    "BounceCount": 10,
    "ApprovalDate": "2012-04-23 14:58:55",
    "UniqueClicks": 1,
    "RetryCount": 128,
    "Splits": [
        {
            "FromEmail": "subscriber.net",
            "TextSpamScore": 0,
            "Subject": "Join Now through April 27",
            "FromName": "Greenbook.net",
            "RecipientList": "Comp actives 063011.csv",
            "HtmlSpamScore": 0.1,
            "SplitNumber": 1,
            "HtmlContentUrl": "http://ows.omeda.com/webservice/rest/brand/FOO/omail/deployment/content/lookup/html/FOO120423006/1/*",
            "TextContentUrl": "http://ows.omeda.com/webservice/rest/brand/FOO/omail/deployment/content/lookup/text/FOO120423006/1/*",
        }
    ],
    "ModificationHistory": [
        {
            "ChangeDescription": "Deployment created (new). Requested date/time is Wed Apr 14 14:00:00 CDT 2010",
            "ChangedBy": "omailAccount1",
            "ChangedDate": "2012-02-03 14:00:00"
        },
        {
            "ChangeDescription": "FinalApproverEmail changed from: '' to: 'omailAccount1'",
            "ChangedBy": "omailAccount1",
            "ChangedDate": "2012-02-03 14:10:00"
        },
        {
            "ChangeDescription": "split #1: message header and content changed",
            "ChangedBy": "omailAccount1",
            "ChangedDate": "2012-02-03 14:20:00"
        },
    ],
    "Testers": [
        {
            "FirstName": "John",
            "LastName": "Doe",
            "EmailAddress": "john@doe.com"
        }
    ],
    "LinkTracking": [
        {
            "ClickCount": 15,
            "LinkUrl": "http://omedastaging.wpengine.com",
            "UniqueClickCount": 7
        }
    ],
    "TotalOpens": 5,
    "OwnerUserId": "omailaccount1",
    "SendingCount": 2,
    "FinalApproverUserId": "omailaccount1",
    "TrackLinks": "true",
    "CampaignId": "",
    "ScheduledDate": "2012-04-23 15:10:00",
    "RequestedDate": "2012-04-23 14:00:00",
    "TrackOpens": "true",
    "Notes": "04/23/2012 - cloned by \"omailaccount1\"\n- see deployment \"FOO Deployment #2\"  trackID=FOO120406005 for additional notes",
    "Status": "Sending",
    "TotalClicks": 1,
    "TrackId": "FOO120423006",
    "CreatedBy": "omailaccount1",
    "CreatedDate": "2012-04-23 14:49:31.84",
    "RecipientCount": 782,
    "IsFiltered": "true",
    "DeploymentTypeId": 10019,
    "DeploymentTypeDescription": "Digital Newsletters",
    "DeploymentDesignation": "Newsletter",
    "ReloadOnqQueryBeforeFinalDeployment": "true",
    "BillingCategoryCode": "O1230005"
}

Failed Submission

A failed request will return a unique submissionId that can be used as needed. A failed submission may be due to several factors:

Status	Description

Status	Description
400 Bad Request	Typically, this error occurs when the request does not follow the specifications.
403 Forbidden	Typically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid.
404 Not Found	Typically, this error occurs with a malformed URL or the resource that is searched for is not found. This can occur if a TrackId in the url is not found in our system.
405 Method Not Allowed	Typically, this error occurs when the resource accessed is not allowed by the HTTP Method utilized. Make sure you employ the appropriate HTTP Method (GET) for this request.

This is not an exhaustive list of errors, but common ones. If an error occurs repeatedly, please contact your Omeda representative.

JSON Example

{
  "Errors" : [
    {
      Error": "Could not find deployment matching track Id FOO0908832" 
    }
  ],
  "SubmissionId" : "C95AE90C-BEC6-41F2-91E2-2BA9168D1D1F"
}

Table of Contents

1 Summary
2 Base Resource URI
3 Technical Requirements
4 Supported Content Types
5 Supported HTTP Methods
6 Field Definition
- - 6.1.1 Lookup Elements
  - 6.1.2 Splits Elements
  - 6.1.3 LinkTracking Elements
  - 6.1.4 ModificationHistory Elements
  - 6.1.5 Testers Elements
- 6.2 GET JSON Request Example
- 6.3 Failed Submission
  - 6.3.1 JSON Example