Search the Omeda Knowledge Base

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/*
brandAbbreviation
is 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-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:

POST
See W3C’s POSTspecs for details.

Field Definition

The following table describes the hierarchical data elements.

Search Elements Submitted – Used for the POST request

Element Name Required? Data Type Description
DeploymentName optional* string text match for deployment name. *required if TrackId is not present
TrackId optional* string text match for deployment trackId. *required if DeploymentName is not present
StartDate optional* string deployments have been clicked after this date. Format: ‘yyyy-MM-dd HH:mm’, Ex. 2012-01-03 09:30. *required if EndDate is present
EndDate optional* string deployments 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 Name Required ? Data Type Description
DeploymentName required string User-specified deployment name
TrackId required string Omail deployment tracking number.
SentDate required string Date that the deployment was sent
Splits required string JSON element containing one or more Split elements (see below)

Split Elements Returned

Element Name Required ? Data Type Description
Split required string Split number
SubjectLine required string Email subject line for this split
Links required string JSON element containing one or more Link elements (see below)

Link Elements Returned

Element Name Required ? Data Type Description
TotalClicks required Integer Sum of all of the NumberOfClicks returned in the Clicks array (see below)
LinkURL required string The URL of the link that was clicked
Clicks required string JSON element containing one or more Click elements (see below)

Click Elements Returned

Element Name Required ? Data Type Description
NumberOfClicks required Integer Number of the times that this customer clicked the link
ClickDate required string Date and time which the customer clicked the link
FirstName required string first name
LastName required string last name
CustomerId required string Internal customer id (for use on certain databases)
EncryptedCustomerId required string The Encrypted Customer Id for the customer
EmailAddress required string Email address for which the click occurred
Keyword optional string Keyword for the link which was clicked
Category optional string Category for the link which was clicked
CategoryValue optional string Category 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:

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 BrandAbbreviation submitted 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 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."
    }
  ]
}
Last Updated On November 30, 2018
Tags:
Knowledge Base Feedback