Skip to content

Search the Omeda Knowledge Base

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 NameRequired?Data TypeDescription
SentCountrequiredintegerNumber of emails that have been successfully sent to email inboxes.
SentDateconditiondateIf the deployment has been sent, the date the deployment was sent. Example: ‘2012-04-23 15:10:11’ (Central Standard Time)
DeploymentNamerequiredstringThe user-entered name of the deployment, designated when the deployment was created.
UniqueOpensrequiredintegerThe number of unique email accounts that opened this deployment.
SplitCountrequiredintegerThe number of splits for this deployment.
BounceCountrequiredintegerThe number of emails that were not accepted into recipient email inboxes after the 72-hour retry period.
ApprovalDaterequireddateThe 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).
UniqueClicksrequiredintegerThe number of unique email addresses that clicked on this deployment.
RetryCountrequiredintegerThe 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.
SplitsrequiredarraySplit 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.
TotalOpensrequiredintegerThe total number of email inboxes that opened the deployment
OwnerUserIdrequiredstringThe Omail account userId that is authorized to edit the deployment.
SendingCountrequiredintegerThe number of emails that are currently in ‘sending’ status. They are in the process of being delivered.
FinalApproverUserIdrequireddateThe Final Approver for the deployment. This is specified when the deployment is created.
TrackLinksrequiredstringtrue / false
LinkTrackingoptionalarrayAn 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
CampaignIdoptionalstringThe Campaign Id specified when the deployment was created, an empty string if none was specified.
ScheduledDaterequireddateThe date the deployment has been scheduled to send.
RequestedDaterequireddateThe date the deployment has been originally requested to be sent
TrackOpensrequiredstringtrue/false
NotesoptionalstringOptional user-specified text that is set when the deployment is created.
StatusrequiredstringThe current status of the deployment. Valid values are : ‘Cancelled’, ‘New’, ‘Sending’,’Scheduled’,’Sent’,’Waiting Review’,’Not Accepted’,’Accepted’,’Submitted’, and ‘Approved’.
TotalClicksrequiredintegerTotal number of clicks registered for this deployment.
TrackIdrequiredstringThe tracking number used to identify the deployment.
CreatedByrequiredstringThe Omail account UserId or service that created the deployment.
CreatedDaterequireddateThe date the deployment was created.
RecipientCountrequiredintegerThe number of recipients being deployed to.
IsFilteredrequiredstringtrue/false
ModificationHistoryrequiredarrayAn array of objects that hold information regarding changes that have been made to the deployment.
TestersoptionalarrayAn array of json objects. Each object contains deployment tester information: First Name, Last Name, and Email Address.
DeploymentTypeIdrequiredintegerThe Deployment Type Identifier in the Omail system. The Cross Reference API can be used to see all available deployment types for a given brand.
DeploymentTypeDescriptionrequiredstringThe Deployment Type description in the Omail system. The Cross Reference API can be used to see all available deployment types for a given brand.
DeploymentDesignationrequiredstringThe deployment designation.
ReloadOnqQueryBeforeFinalDeploymentrequiredbooleanWhether the deployment is set to re-execute an assigned OnQ query, when applicable.
BillingCategoryCodeoptionalstring8 characters billing category if assigned to deployment

Splits Elements

Attribute NameRequired?Data TypeDescription
FromEmailrequiredstringThe ‘From’ email address, specified when the deployment content was created.
TextSpamScorerequireddoubleThe SpamAssassin spam score calculated for the deployment text content. Example: ‘1.2’. Value will be 0.0 if no text content is present.
SubjectrequiredstringThe subject of the email, specified when the deployment content was created.
FromNamerequiredstringThe ‘From’ name, specified when the deployment content was created.
RecipientListconditionalstringThe name of the recipient file used when the deployment was created.
QueryNameconditionalstringThe name of the OnQ query used for the deployment.
OutputCriteriaconditionalstringThe name of the OnQ output criteria used when using an OnQ query for the deployment audience, otherwise ‘Default’.
HtmlSpamScorerequireddoubleThe SpamAssassin spam score calculated for the deployment Html content. Example: ‘1.2’. Value will be 0.0 if no Html content is present.
SequencerequiredintegerThe split number: 1, 2, etc… depending on how many splits the deployment has.
HtmlContentUrlrequiredlinkA 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/* .
TextContentUrlrequiredlinkA 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 NameRequired?Data TypeDescription
CategoryoptionalstringThe category of the link
CategoryValueoptionalstringDescription value for the link category
KeywordsoptionalarrayString array of keywords for the link
LinkNameoptionalstringName of the link
LinkTagoptionalstringTag name of the link
LinkUrlrequiredstringUrl of the link
MessageTyperequiredstringHTML or TEXT, indicating which message body type the link belongs to
Trackedrequiredinteger0 = not tracked, 1 = tracked
WebTrackingrequiredinteger0 = web tracking off, 1 = web tracking on
UniqueClickCountoptionalintegerNumber of total unique clicks for the link
ClickCountoptionalintegerNumber of total clicks for the link

ModificationHistory Elements

Attribute NameRequired?Data TypeDescription
ChangeDescriptionrequiredstringThe description of the change made.
ChangedByrequiredstringThe Omail account UserId that made the change.
ChangedDaterequireddateThe date the change was made.

Testers Elements

Attribute NameRequired?Data TypeDescription
FirstNamerequiredstringThe first name of the tester.
LastNamerequiredstringThe last name of the tester.
EmailAddressrequiredstringThe 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://www.omeda.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:

StatusDescription
400 Bad RequestTypically, this error occurs when the request does not follow the specifications.
403 ForbiddenTypically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid.
404 Not FoundTypically, 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 AllowedTypically, 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"
}
Tags:
Table of Contents
Knowledge Base Feedback