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-appida 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)

Link Elements Returned

Element NameRequired ?Data TypeDescription
TotalClicksrequiredIntegerSum of all of the NumberOfClicks returned in the Clicks array (see below)
LinkURLrequiredstringThe URL of the link that was clicked
ClicksrequiredstringJSON element containing one or more Click elements (see 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

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":"Requal Attempt",
   "TrackId":"OMP171010002S",
   "SentDate":"2017-10-26 09:25",
   "Splits":[  
      {
         "Split":"1",
         "SubjectLine":"Your Subscription Will Expire Soon!",
         "Links":[
            {  
               "TotalClicks":7,
               "LinkURL":"https://www.dragonforms.com/zzzZZZrenew?r=@{encrypted_customer_id}@&pk=ZZZ123",
               "Clicks":[  
                  {  
                     "NumberOfClicks":4,
                     "ClickDate":"2017-10-26 09:28",
                     "FirstName":"Jane",
                     "LastName":"Doe",
                     "CustomerId":"1000012345",
                     "EncryptedCustomerId":"EJDFKL934JF8434",
                     "EmailAddress":"janedoe@fake.com"
                  },
                  {  
                     "NumberOfClicks":3,
                     "ClickDate":"2017-10-27 12:33",
                     "FirstName":"John",
                     "LastName":"Snow",
                     "CustomerId":"1000034567",
                     "EncryptedCustomerId":"AIFGJRKD9445JDE",
                     "EmailAddress":"westeros@notreal.com"
                  }
               ]
            },
            {  
               "TotalClicks":1,
               "LinkURL":"https://www.imdb.com/",
               "Clicks":[  
                  {  
                     "NumberOfClicks":1,
                     "ClickDate":"2017-10-27 12:33",
                     "FirstName":"Kevin",
                     "LastName":"Smith",
                     "CustomerId":"1000666555",
                     "EncryptedCustomerId":"1128E8781801G3U",
                     "EmailAddress":"clerks@isagoodmovie.org"
                  }
               ]
            }
         ]
      },
      {  
         "SubjectLine":"Renew Now!!",
         "Split":"2",
         "Links":[  
            {  
               "TotalClicks":3,
               "LinkURL":"https://www.youtube.com/watch?v=OeP4FFr88SQ",
               "Clicks":[  
                  {  
                     "NumberOfClicks":1,
                     "ClickDate":"2017-10-27 16:20",
                     "FirstName":"Bob",
                     "LastName":"Dylan",
                     "CustomerId":"1000777888",
                     "EncryptedCustomerId":"1TAMB0UR1N3M4N1",
                     "EmailAddress":"blowin@inthewind.answer"
                  },
                  {  
                     "NumberOfClicks":2,
                     "ClickDate":"2017-10-27 16:10",
                     "FirstName":"Robert",
                     "LastName":"Zimmerman",
                     "CustomerId":"1000777889",
                     "EncryptedCustomerId":"AL0V3MINU5Z3R01",
                     "EmailAddress":"notreal@fake.com"
                  }
               ]
            }
         ]
      }
   ]
}

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