REST API
Manage subscribers and campaigns from code. Scoped keys, predictable errors and an OpenAPI 3.1 spec.
A JSON REST API for one newsletter at a time: sync subscribers from your product or CRM, publish campaigns from your CMS, and pull results into your own dashboards. The base URL is:
https://newsletter.sh/api/v1Authentication
An owner creates keys under Settings → API keys. A key looks like nsh_ followed by 40 characters, belongs to one newsletter, and is shown once: only a hash is stored. Send it as a bearer token:
export NSH_KEY="nsh_..." # from Settings → API keys
curl https://newsletter.sh/api/v1/me \
-H "Authorization: Bearer $NSH_KEY"{
"data": {
"newsletter": { "name": "Field Notes", "slug": "field-notes", "subscribers": 4182, "doubleOptIn": true },
"key": { "name": "CRM sync", "prefix": "nsh_8fK2aQ1x", "scopes": ["subscribers:read", "subscribers:write"] }
}
}A newsletter can have up to 20 active keys. Revoke one at any time; it stops working immediately.
Permissions (scopes)
Give each key only what it needs. The settings page has presets for common jobs.
| Scope | Allows |
|---|---|
subscribers:read | Look up and list subscribers and tags |
subscribers:write | Add, update, tag and unsubscribe subscribers |
campaigns:read | Read campaigns and their results |
campaigns:write | Create, edit and delete draft campaigns |
campaigns:send | Send and schedule campaigns |
| Preset | Scopes |
|---|---|
| Full access | All five |
| Sign-up form / CRM sync | subscribers:read, subscribers:write |
| Read only (reporting) | subscribers:read, campaigns:read |
| Publishing (create and send) | campaigns:read, campaigns:write, campaigns:send |
Endpoints
| Endpoint | Scope | Does |
|---|---|---|
GET/me | any key | The newsletter and the key's permissions |
GET/subscribers | subscribers:read | List subscribers (filter by status and tag) |
POST/subscribers | subscribers:write | Add or update one subscriber |
POST/subscribers/batch | subscribers:write | Add or update up to 100 subscribers |
GET/subscribers/{email} | subscribers:read | One subscriber, with welcome-series progress |
PATCH/subscribers/{email} | subscribers:write | Update name, fields and tags |
DELETE/subscribers/{email} | subscribers:write | Unsubscribe |
GET/tags | subscribers:read | Tags in use, with counts |
GET/campaigns | campaigns:read | List campaigns, newest first |
POST/campaigns | campaigns:write | Create a draft from Markdown |
GET/campaigns/{id} | campaigns:read | A campaign with results and clicks per link |
PATCH/campaigns/{id} | campaigns:write | Edit a draft or scheduled campaign |
DELETE/campaigns/{id} | campaigns:write | Delete a draft |
POST/campaigns/{id}/send | campaigns:send | Run the checks, then send (or dry-run) |
POST/campaigns/{id}/schedule | campaigns:send | Schedule a draft |
DELETE/campaigns/{id}/schedule | campaigns:send | Unschedule (back to draft) |
Successful responses wrap the result in data. Timestamps are ISO 8601 strings in UTC. Emails in paths are case-insensitive.
Subscribers
Add or update a subscriber
POST /subscribers creates the reader (201) or merges name, fields and tags into an existing one (200). With double opt-in, the reader gets a confirmation email and the response is 202.
curl -X POST https://newsletter.sh/api/v1/subscribers \
-H "Authorization: Bearer $NSH_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "ada@example.com",
"name": "Ada Lovelace",
"tags": ["vip"],
"fields": { "company": "Analytical Engines" },
"doubleOptIn": false,
"welcome": true
}'doubleOptInandwelcomedefault to the newsletter's settings.- Field keys are lowercase letters, digits and
_, starting with a letter (up to 30 fields, values up to 200 characters). - Someone who unsubscribed can only come back with
"doubleOptIn": true, so they confirm it themselves. Bounced, complained and suppressed addresses are refused with 409.
Batch
curl -X POST https://newsletter.sh/api/v1/subscribers/batch \
-H "Authorization: Bearer $NSH_KEY" \
-H "Content-Type: application/json" \
-d '{"subscribers":[{"email":"ada@example.com"},{"email":"grace@example.com","tags":["beta"]}]}'Up to 100 rows per call. The response counts created, updated and failed, with a result for each row, so one bad address doesn't fail the batch.
Update tags and fields
curl -X PATCH https://newsletter.sh/api/v1/subscribers/ada@example.com \
-H "Authorization: Bearer $NSH_KEY" \
-H "Content-Type: application/json" \
-d '{"addTags":["customer"],"removeTags":["trial"],"fields":{"company":"Acme","coupon":null}}'A null field value removes that field. Send tags instead of addTags/removeTags to replace all tags. Status can't be changed with PATCH; use DELETE to unsubscribe.
List
curl "https://newsletter.sh/api/v1/subscribers?status=subscribed&tag=vip&limit=100" \
-H "Authorization: Bearer $NSH_KEY"Pages hold up to 100 subscribers (50 by default). Pass the response's nextCursor as cursor to get the next page; it is null on the last one. The tag filter is applied within each page, so a page can hold fewer than limit rows while more remain.
Campaigns
Create a draft from Markdown
curl -X POST https://newsletter.sh/api/v1/campaigns \
-H "Authorization: Bearer $NSH_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "This week at Acme",
"preheader": "Three things we shipped",
"markdown": "## Hello {{first_name|there}}\n\nWe shipped **three** things.\n\n- Faster search\n- Dark mode\n\n[Read the changelog](https://acme.com/changelog){button}"
}'Markdown supports headings, bold, italic, code, links, lists, quotes, --- dividers, images (), buttons ([Label](https://…){button}) and merge fields. Add segmentId to send to a segment. Drafts and scheduled campaigns can be edited with PATCH.
Check, then send
# Dry run: blockers, warnings and recipient count. Nothing is sent.
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/send \
-H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
-d '{"dryRun":true}'
# Send. Warnings must be acknowledged, just like the Send button.
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/send \
-H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
-d '{"acknowledgeWarnings":true}'{
"ok": true,
"status": "sending",
"blockers": [],
"warnings": [],
"recipients": 4182,
"warmup": null
}Blockers return 422 send_blocked; unacknowledged warnings return 409 warnings_not_acknowledged. Both list what to fix.
Schedule
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/schedule \
-H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
-d '{"scheduledAt":"2026-12-01T09:00:00Z"}'Between one minute and one year ahead. DELETE the same path to unschedule. GET /campaigns/{id} returns live results (sent, delivered, opens, clicks, unsubscribes, bounces, complaints and rates) and clicks per link.
Errors
Errors use standard HTTP status codes and a consistent JSON body:
{
"error": "insufficient_scope",
"message": "This key doesn't have the \"subscribers:write\" permission. Create a key that does in Settings → API keys."
}| Status | Codes |
|---|---|
| 400 | invalid_request |
| 401 | missing_api_key, invalid_api_key |
| 403 | insufficient_scope, plan_limit (the account's subscriber limit is reached) |
| 404 | not_found |
| 409 | suppressed, unsubscribed, not_editable, not_schedulable, warnings_not_acknowledged, … |
| 422 | invalid_email, invalid_content, invalid_segment, missing_subject, invalid_time, send_blocked |
| 429 | rate_limited |
Rate limits
Each key can make 120 requests in a burst, then 2 per second sustained. A batch call costs one request per 10 rows. Over the limit you get 429 rate_limited; wait a second or two and retry with backoff.
OpenAPI spec
The full API is described in an OpenAPI 3.1 document at /api/v1/openapi.json. Import it into Postman or Insomnia, or generate a typed client in any language. Each operation lists the scope it needs as x-required-scope.
curl https://newsletter.sh/api/v1/openapi.json -o newsletter-sh-openapi.jsonWant to react to events instead of polling? See Webhooks.