This document explains how to query the promotions API.
GET Promotions by Newsletter
Get upcoming promotions of a given brand newsletter, with dates after today (GMT).
You must pass your brand's API key as a bearer token. This key will be generated for your brand by the Letterhead team upon request.
HTTP Request
GET
https://api.tryletterhead.com/api/v2/promotions/ |
Query Parameters
Parameter | Status | Description |
date | optional |
A date string formatted as 2020-04-03 (YYYY-MM-DD), which will filter promotions to a given day:
|
mjml | optional |
A boolean that will return a promotion's MJML template.
|
resolveContent | optional |
A boolean telling the API to return a promotion's full HTML (markup).
|
JS
const url = new URL(
"https://api.tryletterhead.com/api/v2/promotions/"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {token}",
};
fetch(url, {
method: "GET",
headers: headers,
})
.then(response => response.json())
.then(json => console.log(json));
PHP
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.tryletterhead.com/api/v2/promotions/',
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {token}',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Python
import requests
import json
url = 'https://api.tryletterhead.com/api/v2/promotions/'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()
Example response (200)
All responses are UTF-8 encoded json.
[ { "adTypeId": 126,
"advertiserLogo": null, "blurb": "Join us for the third annual Bitter Coffee Bean chug-off, where we do our best not to burn our mouths.",
"brandId": 1,
"callToAction": "Click here to pre-order today!",
"callToActionUrl": "https://black-bitter-coffee.com/rsvp",
"channelId": 1,
"content": "",
"dateStart": "2020-09-18",
"emoji": "☕",
"heading": "Bitter Coffee Bean Chug-off",
"id": 1923,
"markup": "",
"metrics": {
"adId": 1923,
"clicks": 0,
"reads": 0,
"uniqueReads": 0,
"updatedAt": "2020-10-29T14:56:28.570-04:00"
},
"pixel": "https://newsletters.whereby.us/rangers/tdp1sybfct/*|UNIQID|*/a.jpg",
"promoterDisplayName": "We love coffee",
"promoterImage": null,
"promoterImageAlternativeText": "",
"resolvedCallToActionUrl": "",
"uniqueId": "tdp1sybfct",
"scheduledDate": "2020-10-21T18:33:13.736-04:00",
"status": 0
},
{ "adTypeId": 126,
"advertiserLogo": null, "blurb": "Get your message in front of our community and support Black Bitter Coffee Times when you place a promotion here. \n",
"brandId": 1,
"callToAction": "Get started today",
"callToActionUrl": "https://black-bitter-coffee.com/rsvp",
"channelId": 1,
"content": "",
"dateStart": "2020-09-25",
"emoji": "😀",
"heading": "Help us help you",
"id": 2045,
"markup": "",
"metrics": {
"adId": 2045,
"clicks": 10,
"reads": 50,
"uniqueReads": 25,
"updatedAt": "2020-10-29T14:56:28.570-04:00"
},
"pixel": "https://newsletters.whereby.us/rangers/a32yrqydgr/*|UNIQID|*/a.jpg",
"promoterDisplayName": "Friends of Black Bitter Coffee",
"promoterImage": null,
"promoterImageAlternativeText": "",
"resolvedCallToActionUrl": "",
"uniqueId": "a32yrqydgr",
"scheduledDate": "2020-10-27T19:18:53.000-04:00",
"status": 0
},
]
Response details
Property | Type | Description |
adTypeId | Integer | The id of the promotion type. |
advertiserLogo | String | If Promoter logo is enabled for this promotion type, a URL to the brand or company's Logo. 300x300. |
blurb | String | If short text is enabled for this promotion type, the main copy or text of the promotion. |
brandId | Integer | The id of the brand for which the promotion is associated. |
CallToAction | String | If Call to action is enabled for this promotion type, the call to action text for the promotion. Typically used as link or button text. |
callToActionUrl | String | The raw call to action url for the promotion. (This should not be used in production because it does not enable click tracking, however it may be used for testing or promotion approval). |
channelId | Integer | The id of the channel for which the promotion is associated. |
content | String | If expanded text is enabled for this promotion type, the expanded text content, a light-markup content. |
dateStart | String | The date of publication for the promotion. |
emoji | String | If emoji is enabled for this type, the emoji for the promotion. Typically emojis are used in the promotion headline. All emoji are emoji 1.0. |
heading | String | If heading is enabled for this promotion type, the headline for the promotion. |
id | Integer | The id of the promotion. |
markup | String | The promotion content inserted into the HTML template — to see the markup content, you must pass resolveContent=true in the API call: https://api.tryletterhead.com/api/v2/promotions/?resolveContent=true |
metrics.adId | Integer | The id of the promotion. |
metrics.clicks | Integer | The number of times a promotion’s resolvedCallToActionUrlis clicked. |
metrics.reads | Integer | The total number of times a promotion was viewed. |
metrics.uniqueReads | Integer | The number of unique views a promotion got. |
metrics.updatedAt | String | When the promotion metrics was last updated. |
pixel | String | The URL of the tracking pixel for the promotion. The {uniqueValuePerReader} parameter must be substituted with a unique alphanumeric string to represent a single user in order to differentiate unique from repeat views. |
promoterDisplayName | String | The display name of the company or organization to be presented with the promotion. |
promoterImage | String | If Image is enabled for this type, the url of the image associated with the promotion. |
promoterImageAlternativeText | String | The Alt text for the promotion image. |
resolvedCallToActionUrl | String | The link-resolved url to the callToActionUrl, which should be used in production to enable click tracking. |
uniqueId | String | The uniqueID of the promotion. |
scheduledDate | String | The date of publication for the promotion. |
status | Integer |
This is the promotion publication status 0 = the promotion is scheduled. 1 = the promotion is pending publication, meaning the date of publication has come but we haven't received any metrics. 2 = the promotion is published. |