Search the Omeda Knowledge Base

< All Topics
Print

Email Clicks

Summary

This service retrieves Omail data related to clicks on links in emails using various parameters.

Base Resource URI

Production: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/omail/click/search/*

Testing: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/omail/click/search/*

brandAbbreviationis the abbreviation for the brand

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-typea 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.JSONapplication/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:POSTSee W3C’s POSTspecs for details.

Field Definition

The following table describes the hierarchical data elements.

Search Elements Submitted – Used for the POST request

Element NameRequired?Data TypeDescription
DeploymentNameoptional*stringtext match for deployment name. *required if TrackId is not present
TrackIdoptional*stringtext match for deployment trackId. *required if DeploymentName is not present
StartDateoptional*stringdeployments have been clicked after this date. Format: ‘yyyy-MM-dd HH:mm’, Ex. 2012-01-03 09:30. *required if EndDate is present
EndDateoptional*stringdeployments have been clicked prior to this date. Format: ‘yyyy-MM-dd HH:mm’, Ex. 2012-02-03 21:30. *required if StartDate is present

Deployment Click Elements Returned

Element NameRequired ?Data TypeDescription
DeploymentNamerequiredstringUser-specified deployment name
TrackIdrequiredstringOmail deployment tracking number.
SentDaterequiredstringDate that the deployment was sent
SplitsrequiredstringJSON element containing one or more Split elements (see below)

Split Elements Returned

Element NameRequired ?Data TypeDescription
SplitrequiredstringSplit number
SubjectLinerequiredstringEmail subject line for this split
LinksrequiredstringJSON element containing one or more Link elements (see below)
Element NameRequired ?Data TypeDescription
TotalClicksrequiredIntegerSum of all of the NumberOfClicks returned in the Clicks array (see Click Elements Returned below)
LinkURLrequiredstringThe URL of the link that was clicked
ClicksrequiredstringJSON element containing one or more Click elements (see Click Elements Returned below)
TotalUnrealClicksrequiredIntegerSum of all of the NumberOfUnrealClicks (bot clicks) returned in the unrealClicks array (see UnrealClick Elements Returned below)
UnrealClicksrequiredstringJSON element containing one or more unrealClick (bot clicks) elements (see UnrealClick Elements Returned below)

Click Elements Returned

Element NameRequired ?Data TypeDescription
NumberOfClicksrequiredIntegerNumber of the times that this customer clicked the link
ClickDaterequiredstringDate and time which the customer clicked the link
FirstNamerequiredstringfirst name
LastNamerequiredstringlast name
CustomerIdrequiredstringInternal customer id (for use on certain databases)
EncryptedCustomerIdrequiredstringThe Encrypted Customer Id for the customer
EmailAddressrequiredstringEmail address for which the click occurred
KeywordoptionalstringKeyword for the link which was clicked
CategoryoptionalstringCategory for the link which was clicked
CategoryValueoptionalstringCategory value for the link which was clicked

UnrealClick Elements Returned

Element NameRequired ?Data TypeDescription
UnrealClicksrequiredstringJSON element containing one or more UnrealClick (bot) Responses (see UnrealClick Reasons Returned below)
FirstNamerequiredstringfirst name
LastNamerequiredstringlast name
CustomerIdrequiredstringInternal customer id (for use on certain databases)
EncryptedCustomerIdrequiredstringThe Encrypted Customer Id for the customer
EmailAddressrequiredstringEmail address for which the click occurred
KeywordoptionalstringKeyword for the link which was clicked
CategoryoptionalstringCategory for the link which was clicked
CategoryValueoptionalstringCategory value for the link which was clicked

UnrealClick Reasons Returned

Element NameRequired ?Data TypeDescription
NumberOfUnrealClicksrequiredIntegerNumber of the times that this customer (bot) clicked the link
ClickDaterequiredstringDate and time which the customer (bot) clicked the link
ReasonrequiredstringCode for unreal click reason (see UnrealClick Reason Codes Legend below)

UnrealClick Reason Codes Legend

Reason codeReason Code DescriptionWhich Clicks Are Negated?
1Two clicks within 2000 milliseconds (2 seconds)Offending Click
2More than 10 clicks within 30 secondsAll Clicks
3Percentage of fake clicks exceeds 50%First Click where the Second Click met Reason Code 1
4Number of unique source IP address exceeds 12All Clicks
5Total number of clicks received exceeds 200All Clicks
6Number of unique user agents exceeds 9All Clicks
7User agent of click is within pre-defined listOffending Click
8Source IP address of click is within Ignored IPs list {tracking.agent_ip_range_ignore_list}Offending Click
9Source IP address of click is within pre-defined listOffending Click
10Link was clicked 5 seconds after sendOffending Click

Request Example #1

This example would search the Omail system for clicks for the deployment with TrackId ‘OMP171010002S’ which occurred between 2017-10-26 00:25 and 2017-10-28 23:59.

{
    "TrackId": "OMP171010002S",
    "StartDate": "2017-10-26 00:25",
    "EndDate": "2017-10-28 23:59"
}

Request Example #2

This example would search the Omail system for clicks for the deployment with name ‘Requal Attempt’ which occurred between 2017-10-26 00:25 and 2017-10-28 23:59.

{
    "DeploymentName": "Requal Attempt",
    "StartDate": "2017-10-26 00:25",
    "EndDate": "2017-10-28 23:59"
}

Response Example

JSON Example

{
   "DeploymentName":"Verification Test",
   "splits":[
      {
         "SubjectLine":"Verification Tests",
         "links":[
            {
               "TotalClicks":67,
               "TotalUnrealClicks":5,
               "LinkURL":"http://my.omeda.com",
               "clicks":[
                  {
                     "EncryptedCustomerId":"",
                     "Category":"",
                     "NumberOfClicks":32,
                     "Keyword":"",
                     "FirstName":"Elist",
                     "CategoryValue":"",
                     "CustomerId":"",
                     "LastName":"Omeda",
                     "ClickDate":"2011-05-23 16:10",
                     "EmailAddress":"elist@omeda.com"
                  },
                  {
                     "EncryptedCustomerId":"",
                     "Category":"",
                     "NumberOfClicks":1,
                     "Keyword":"",
                     "FirstName":"Jeff",
                     "CategoryValue":"",
                     "CustomerId":"",
                     "LastName":"Bezos",
                     "ClickDate":"2011-05-23 16:14",
                     "EmailAddress":"jbezos@omeda.com"
                  }
               ],
               "unrealClicks":[
                  {
                     "EncryptedCustomerId":"",
                     "Category":"",
                     "Keyword":"",
                     "FirstName":"John",
                     "CategoryValue":"",
                     "CustomerId":"123",
                     "LastName":"Doe",
                     "UnrealClicks":[
                        {
                           "NumberOfUnrealClicks":1,
                           "ClickDate":"2011-05-23 16:10",
                           "Reason":1
                        },
                        {
                           "NumberOfUnrealClicks":2,
                           "ClickDate":"2011-05-23 16:10",
                           "Reason":3
                        }
                     ],
                     "EmailAddress":"jdoe@omeda.com"
                  },
                  {
                     "EncryptedCustomerId":"",
                     "Category":"",
                     "Keyword":"",
                     "FirstName":"Bill",
                     "CategoryValue":"",
                     "CustomerId":"",
                     "LastName":"Gates",
                     "UnrealClicks":[
                        {
                           "NumberOfUnrealClicks":1,
                           "ClickDate":"2011-05-23 16:10",
                           "Reason":1
                        },
                        {
                           "NumberOfUnrealClicks":1,
                           "ClickDate":"2011-05-23 16:10",
                           "Reason":3
                        }
                     ],
                     "EmailAddress":"bgates@omeda.com"
                  }
               ]
            }
         ],
         "Split":"1"
      }
   ],
   "SentDate":"2011-05-23 00:00",
   "TrackId":"CGM110520002"
}

Failed Submission

A failed POST 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 BrandAbbreviation submitted 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 correct HTTP Method (POST) 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

{
  "SubmissionId" : "C95AE90C-BEC6-41F2-91E2-2BA9168D1D1F",
  "Errors" : [
    {
      "Error": "The AppId submitted is forbidden access."
    }
  ]
}
Tags:
Table of Contents
Scroll to Top