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

GET 

                                                                                 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