LetterFlight is API-first: everything the dashboard does — adding subscribers, sending campaigns, reading delivery stats — is a plain HTTPS JSON call.
You are integrating the LetterFlight newsletter API into an existing codebase.
BASE URL: https://letterflight.com/api/v1
AUTH: send the header "Authorization: Bearer <API_KEY>" with every call.
API keys look like sk_... and are created in the LetterFlight dashboard:
https://letterflight.com/dashboard (a key is shown exactly once when created)
WHAT LETTERFLIGHT IS
A hosted newsletter service with deliverability guardrails that cannot be
turned off. Design around them, do not try to bypass them:
1. Double opt-in: POST /subscribers always creates the address as "pending"
and emails it a confirmation link. Only "confirmed" subscribers ever
receive campaigns. There is no API to skip the confirmation email.
2. Every email automatically carries per-recipient List-Unsubscribe headers
plus RFC 8058 one-click unsubscribe. You never add these yourself.
3. Frequency cap: a subscriber gets at most 5 campaign emails per 24 hours.
Extra recipients are skipped and counted in the response (skippedFreq).
4. Hard bounces are detected automatically; the address becomes "bounced"
and is never mailed again.
ENDPOINTS (all JSON)
- GET /me -> {"user":{...},"quota":{used,limit,
remaining}} — account + plan quota usage
- GET /auth/me -> {"user":{...}} verify the key
- POST /subscribers {"email","name"?} -> 201 {"id","email","status":"pending"}
adding an already pending/confirmed address -> 200 with the existing record;
re-adding an unsubscribed address reopens it as pending and re-sends the
- GET /subscribers -> {"subscribers":[...],"count":N}
- GET /subscribers?status=confirmed -> filter: pending|confirmed|unsubscribed|bounced
- GET /subscribers?limit=50&offset=0 -> paginate; response adds "total" plus the
limit/offset you passed (limit caps at 500). Omit for the full list.
- GET /subscribers/:id -> subscriber object, or 404
- DELETE /subscribers/:id -> {"deleted":1}
- POST /send {"subject","body","html"?,"mode"?} -> 201 {"campaignId","requested",
"sent","failed","bounced","skippedFreq","mode"}
body (plain text) is required; html is the optional HTML version.
mode defaults to "blast" (mails every confirmed subscriber). Use
mode "test" to send ONE copy to your own account email — it never
touches subscribers, deliveries or frequency caps. Always preview
with mode "test" first.
Put {{unsubscribe_url}} anywhere in body or html; it is replaced per
recipient with their unique unsubscribe link before sending.
In HTML campaigns LetterFlight also injects open tracking and rewrites
links through a redirector — engagement numbers appear on the campaign.
- POST /campaigns {"subject","body","html"?,"scheduled_at"} -> 201 {"campaignId",
"status":"scheduled","scheduled_at"}
scheduled_at: a FUTURE UTC time "YYYY-MM-DD HH:MM:SS". Nothing is sent
at creation; the campaign fires when its time passes and then behaves
exactly like a POST /send blast (same guardrails).
- DELETE /campaigns/:id -> {"deleted":1,"status":"cancelled"}
cancels a scheduled campaign. A sent campaign cannot be cancelled
(409). A campaign owned by someone else answers 404.
- GET /campaigns -> {"campaigns":[...]} recent sends;
every row carries "status" (scheduled|sending|sent|failed|cancelled),
"scheduled_at", "html", plus engagement numbers: "delivered", "opened"
(unique subscribers), "open_count", "open_rate", "clicked" (unique),
"click_count", "click_rate" (rates are relative to delivered; null if
nothing was delivered yet)
- GET /campaigns/:id -> {"campaign":{...},"deliveries":[...]}
the campaign object carries the same engagement numbers.
TYPICAL INTEGRATIONS
- Sign-up flow: after a user registers in the app, POST /subscribers with
their email. Set expectations: they must click the confirmation email.
- Regular sending: POST /send with the newsletter content. Only confirmed
subscribers receive it; the response tells you exactly how many.
- Scheduled sending: POST /campaigns with a future scheduled_at; cancel
with DELETE /campaigns/:id if plans change before it fires.
- Engagement reporting: poll GET /campaigns after a send and read the
opened / clicked / *_rate numbers (unique subscribers; rates relative to
delivered).
TASK
1. Store my API key in an env var (suggest LETTERFLIGHT_API_KEY) and read it
from there. Never hardcode it.
2. Create one small module that wraps these endpoints with the base URL and
auth header. No new dependencies beyond what my project already uses.
3. Wire it in at the sensible places: add-to-newsletter on sign-up, and a
send-newsletter command/function.
4. Print the curl commands I can run to verify the integration end to end.
# 1. verify your key + see your plan quota
curl https://letterflight.com/api/v1/me -H "Authorization: Bearer sk_..."
# 2. add a subscriber (they get a confirmation email; double opt-in is not optional)
curl -X POST https://letterflight.com/api/v1/subscribers \
-H "Authorization: Bearer sk_..." -H "content-type: application/json" \
-d '{"email":"reader@example.com","name":"Jane Doe"}'
# 3. send a campaign (only confirmed subscribers receive it)
curl -X POST https://letterflight.com/api/v1/send \
-H "Authorization: Bearer sk_..." -H "content-type: application/json" \
-d '{"subject":"Issue #12","body":"Hello reader. Unsubscribe: {{unsubscribe_url}}"}'
# 4. check delivery + engagement counters (opens, clicks, rates)
curl https://letterflight.com/api/v1/campaigns -H "Authorization: Bearer sk_..."
Create your key in the dashboard — it is shown exactly once, and can be revoked there at any time.
| Method & path | What it does | Returns |
|---|---|---|
GET /me | Current account + plan quota usage | {"user":{...},"quota":{"used","limit","remaining"}} |
GET /auth/me | Verify the key / current account | {"user":{...}} |
POST /subscribers | Add subscriber — always pending, confirmation email is sent automatically (double opt-in). Re-adding a pending/confirmed address returns the existing record with 200. | 201 {"id","email","status"} |
GET /subscribers | List; optional ?status= filter (pending|confirmed|unsubscribed|bounced) and optional pagination ?limit=&offset= (limit caps at 500; adds total to the response; omit for the full list) | {"subscribers":[...],"count":N} |
GET /subscribers/:id | One subscriber | object / 404 |
DELETE /subscribers/:id | Remove permanently | {"deleted":1} |
POST /send | Campaign to confirmed subscribers only. body (text) required, html optional. {{unsubscribe_url}} placeholder is replaced per recipient. Optional mode:"test" sends one copy to your own account email instead — never touches subscribers or caps. HTML campaigns get open tracking + link rewriting injected automatically. | 201 {"campaignId","requested","sent","failed","bounced","skippedFreq","mode"} |
POST /campaigns | Schedule a campaign — nothing is sent at creation; it fires when scheduled_at (future UTC YYYY-MM-DD HH:MM:SS) passes, with the same guardrails as POST /send. | 201 {"campaignId","status":"scheduled","scheduled_at"} |
DELETE /campaigns/:id | Cancel a scheduled campaign (a sent one answers 409) | {"deleted":1,"status":"cancelled"} |
GET /campaigns | Recent campaigns with counters + lifecycle (status / scheduled_at / html) (last 100), plus engagement: delivered, opened / open_count / open_rate, clicked / click_count / click_rate | {"campaigns":[...]} |
GET /campaigns/:id | One campaign + per-status delivery counts + the same engagement numbers | {"campaign":{...},"deliveries":[...]} |
Engagement semantics: opened/clicked count unique subscribers
(a subscriber who opens twice still counts once; open_count is the raw total), rates are relative to
delivered and are null until something has been delivered. Text-only campaigns (no
html) can record clicks but not opens.
| Surface | Limit | On limit |
|---|---|---|
| Account registration | 5 per IP / 10 min | 429 |
| Public subscribe page POST | 3 per IP / hour | 429 page |
| Early-access leads | 5 per IP / hour | 429 |
Landing funnel beacons (/api/v1/track) | 60 per IP / min | silently dropped (200) |
Email open/click pixels (/t/o, /t/c) | 300 per IP / min | event dropped, response unchanged |
| Free tool: email auth check | 10 per IP / hour | 429 |
Authenticated API (Authorization: Bearer sk_…) | no hard limit — be reasonable; sending is throttled per subscriber (5 campaign emails / 24h) instead | — |
| Status | Meaning |
|---|---|
400 | Invalid input (missing subject, bad email, bad scheduled_at, non-http(s) click-through URL…) |
401 | Missing or invalid key — send Authorization: Bearer sk_… or X-API-Key |
402 | Plan subscriber limit reached (response carries upgrade_url on free) |
403 | Forbidden — email address not verified yet, or the complaint-rate circuit breaker paused sending (response carries the numbers) |
404 | Not found or not yours (ownership is never leaked) |
409 | Conflict — e.g. cancelling an already-sent campaign |
413 | Payload too large (CSV batches: 100 rows / 2 MB default, 5,000 rows / 5 MB attested migration) |
422 | Address previously hard-bounced; re-subscription refused |
429 | Rate limited — slow down (see table above) |
500 | Internal error — retry with backoff |
502 | The confirmation email could not be sent (row stays pending; retry by re-adding the address) |
pending and must click the confirmation email. Design your UX around the
"check your inbox" step — don't promise users they're on the list before they confirm.skippedFreq — not an error.List-Unsubscribe + RFC 8058 one-click headers. Use the
{{unsubscribe_url}} placeholder in your content to also link it in the body.POST /send with
mode:"test" sends a single copy to your own account email — subscribers,
frequency caps and delivery records stay untouched. Never use a real blast to preview.bounced; it stops receiving mail and re-subscription is refused.sk_... value immediately —
the dashboard only ever shows the prefix afterwards. Revoke and re-create any time
from the dashboard.LetterFlight · newsletter hosting that reaches the inbox · every email includes one-click unsubscribe