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/*
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 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." } ] }