Promotions API reference

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

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:


Example requests

const url = new URL(
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));
$client = new \GuzzleHttp\Client();
$response = $client->get(
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {token}',
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = ''
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {token}'
response = requests.request('GET', url, headers=headers)

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": "",
"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": "*|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": "",
"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": "*|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=truein the API call:
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.