List newsletter tags

GET

/api/v3/letters/tags

const url = 'https://api.tryletterhead.com/api/v3/letters/tags?api=true&scope=channel';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/letters/tags?api=true&scope=channel' \
  --header 'Authorization: Bearer <token>'

List the tags available for organizing newsletters — the same tags shown on a letter’s tags field and in the composer’s tag picker.

Pass scope to control which tags come back:

Omit scope to get the tags currently applied to letters across your company (or one channel, with channelSlug). This default mode mirrors each tag as a taxonomy term and includes some internal fields alongside uniqueId and name.
channel — tags scoped to a single channel (pass channelSlug).
company — tags scoped to the whole company, not tied to any one channel.
picker — every tag available to assign, company- and channel-scoped together — the same list the composer’s tag picker uses.

With scope supplied, each tag comes back in the same compact shape as Create a newsletter tag — {uniqueId, name, channelId} — where channelId identifies whether the tag is scoped to a specific channel or to the company as a whole.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

When true, tells the endpoint you are authenticating with a company API key (the key you generate under a company’s administrative settings) rather than a logged-in user session. For API integrations you will almost always set this to true.

channelSlug

string

(optional) Restrict results to tags on a specific channel.

keyword

string

(optional) Free-text search across tag names.

scope

string

Allowed values: channel company picker

(optional) One of channel, company, or picker — see the description above. Omit for the default “tags currently applied” list.

Responses

200

List newsletter tags

application/json

object

items

Array<object>

A tag. Shown here are the fields common to both response shapes — the default (no scope) response also includes a few internal taxonomy fields (id, taxonomyId, parentTermId, createdAt, updatedAt).

object

uniqueId

string

name

string

channelId

Present when scope is supplied — see the description above.

integer

message

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": "t4kq9x2mle",
      "name": "Product updates",
      "channelId": 999999999
    },
    {
      "uniqueId": "b7pz3y1ork",
      "name": "Community spotlight",
      "channelId": 54212
    }
  ],
  "message": "",
  "total": 2
}

Still can’t find what you need? Contact support.