Installing the TypeScript SDK and CLI

You don’t have to write HTTP requests by hand to use the Letterhead API. Letterhead publishes two tools on npm, both built from the same API description as the API reference, so they cover every operation in it:

• @tryletterhead/sdk, a TypeScript package for your own code, with a typed method for every operation.
• @tryletterhead/cli, the letterhead command-line tool, for your terminal and scripts.

Before you start

• Node 18 or later, or for the TypeScript package, any runtime with a built-in fetch.
• A company API key. See Creating and managing API keys.
• Your API address, if your company signs in on its own subdomain. Swap api in for app: if you sign in at acme.app.tryletterhead.com, your API address is https://acme.api.tryletterhead.com. If you sign in at the plain app.tryletterhead.com, you don’t need to set one.

Keep your API key on a server. A company API key can read and change your whole audience, and anything in code that runs in a browser is public. Use the package in your own backend or a serverless function, and have a website or React app call that instead. Keep the key out of shared shells and scripts too.

Install the TypeScript package

npm install @tryletterhead/sdk

Create a client with your key, then make your first call. This adds a contact (or updates the one with that email) and tags them:

import { createLetterheadClient } from '@tryletterhead/sdk';

const letterhead = createLetterheadClient({
  apiKey: process.env.LETTERHEAD_API_KEY!,
  // Only if your company signs in on its own subdomain:
  // baseUrl: 'https://acme.api.tryletterhead.com',
});

await letterhead.contacts.upsert({ email: '[email protected]', firstName: 'Pat', tags: ['vip'] });

What to know as you build:

• Every operation has a method, grouped by area: contacts, segments, letters, curations, promotions, channels, metrics, automations, transactionalEmail, teams, agents and links. Your editor lists the methods in each and tells you what they take and return. Each takes one argument with path, query and body where the operation has them, and returns the response body.
• Shortcuts for the common jobs. contacts has upsert, get, update and delete; tags has create, list, get, update, delete, addToContacts and removeFromContacts; letters has list, get, create, update and delete.
• Errors throw. When the API answers with an error, the method throws a LetterheadError carrying the status and the response body, so you can handle failures in one place.
• You never pass api=true. The package adds it to every request.

For working examples of common tasks, see Code samples. The package’s page on npm has more.

Install the command-line tool

npm install -g @tryletterhead/cli
export LETTERHEAD_API_KEY=<your-api-key>
# Only if your company signs in on its own subdomain:
export LETTERHEAD_BASE_URL=https://acme.api.tryletterhead.com

You can also run it once without installing, with npx @tryletterhead/cli --help. It reads your key from LETTERHEAD_API_KEY (you can pass --api-key instead, but then the key ends up in your shell history) and never saves it anywhere.

Your first call adds a contact and tags them:

letterhead contacts upsert --email [email protected] --first-name Pat --tag vip

What to know as you build:

• Commands are letterhead <group> <command>. letterhead --help lists the groups, letterhead <group> --help lists a group’s commands, and letterhead <group> <command> --help shows a command’s options.
• Options are the operation’s parameters, in kebab-case (--first-name for firstName). Repeat an option to send a list (--tag vip --tag webinar). Send anything else as JSON with --body, from a file (--body @contact.json) or standard input (--body -).
• Answers print as JSON on standard output. If the API returns an error, it’s printed to standard error and the command exits with a non-zero code, so scripts can tell something went wrong.
• Deletes ask first. A command that deletes something asks you to type yes at a terminal. Anywhere else, such as a script or a coding agent, it refuses unless you add --yes.
• Uploading files isn’t supported yet. Use the TypeScript package for those.

Keeping up to date

New endpoints reach the package and the tool in a new version soon after they appear in the API reference. Update them to pick those up.

If something in the package or the tool doesn’t match the API reference, contact support.