---
name: newsletters
description: manage tinysend newsletters — create a newsletter, add subscribers (double opt-in, import/export), write and send posts, schedule sends, run waitlists with referrals, connect custom domains, track opens and clicks. use when sending newsletters or managing subscribers.
license: MIT
compatibility: requires network access to api.tinysend.com (see the platform skill for auth)
---

# newsletters

manage newsletters, subscribers, and posts in tinysend. this is the core workflow: create a newsletter, add subscribers, write a post, send it.

## newsletters

each newsletter has its own subscribers, sender domain, and settings.

types: newsletter, waitlist, announcement

(the REST paths are `/v1/lists/...` — "list" is the API resource name for a newsletter; the MCP tools use `list_newsletters` / `get_newsletter` / `create_newsletter`.)

```
GET    /v1/lists                          all your newsletters
POST   /v1/lists                          create a newsletter
GET    /v1/lists/:id                      newsletter details
PATCH  /v1/lists/:id                      update settings
DELETE /v1/lists/:id                      delete a newsletter
```

newsletter settings: name, description, sender name/email/domain, custom domain, tracking (opens/clicks — off by default), public archive, subscriber count visibility.

## subscribers

subscribers belong to a newsletter. statuses: pending, active, unsubscribed, undeliverable.

```
GET    /v1/lists/:id/subscribers          list (filter by status, search)
POST   /v1/lists/:id/subscribers          add one
PATCH  /v1/lists/:id/subscribers/:sid     update
DELETE /v1/lists/:id/subscribers/:sid     remove
POST   /v1/lists/:id/subscribers/import   bulk import
GET    /v1/lists/:id/subscribers/export   export CSV
```

### double opt-in

adding a subscriber never auto-verifies. by default the subscriber is created `pending` and a confirmation email is sent. they become `active` after clicking the link. pass `"verified": true` ONLY when you have already verified consent upstream.

### subscriber data

email, name, status, source, engagement (last open/click), deliverability (bounce history), geo (country, city), device info.

## posts

posts are emails sent to a newsletter. statuses: draft, published, sending, sent.

```
GET    /v1/lists/:id/posts               list posts
POST   /v1/lists/:id/posts               create a draft
GET    /v1/lists/:id/posts/:pid          post + stats
PATCH  /v1/lists/:id/posts/:pid          update a draft
DELETE /v1/lists/:id/posts/:pid          delete a draft
POST   /v1/lists/:id/posts/:pid/send     send to all subscribers
POST   /v1/lists/:id/posts/:pid/schedule schedule for later
```

each post has: subject, body (HTML + text), slug, short ID, send stats (batches, delivered, failed).

sources: email (forward to the newsletter address), web editor, API.

## sending

sending is batched and tracked per post: total subscribers, total batches, sent count, failed count, started/completed timestamps. can be paused or cancelled.

## waitlists

a newsletter with type=waitlist collects signups with position tracking, referrals, and batch invites.

```
POST   /v1/lists                          create with type=waitlist
POST   /v1/lists/:id/join                 join (email or agent identity)
GET    /v1/lists/:id/subscribers           entries with waitlist_status + position
POST   /v1/lists/:id/invite               batch invite { count } | { subscribers: [ids] } | { all: true }
GET    /v1/lists/:id/stats                 total, waiting, invited, accepted, conversion_rate
```

optional ref code credits a referral. returns position + referral_url.

## custom domains

a newsletter can have a custom domain for its public site, and a custom sender domain for outgoing email — two independent features:

```
GET    /v1/lists/:id/site-domain          status + DNS records (found/not-found) + next step
POST   /v1/lists/:id/site-domain          connect a domain ({ domain, www_enabled? })
POST   /v1/lists/:id/site-domain/check    re-check DNS + SSL now
DELETE /v1/lists/:id/site-domain          disconnect (site stays on tinysend.com subdomain)

GET    /v1/lists/:id/sender               sender mode + records + next step
PUT    /v1/lists/:id/sender               set mode ({ type: tinysend|custom_domain|gmail, name?, email?, domain? })
POST   /v1/lists/:id/sender/check         re-verify sender DNS via Postmark now
DELETE /v1/lists/:id/sender               reset to @tinysend.com default
```

after connecting, the response includes the exact DNS records to add. verification runs automatically every minute and the owner is emailed when the domain goes live — no polling needed. subdomains need one CNAME to sites.tinysend.com; naked domains also get a TXT record and need ALIAS/flattened-CNAME support.

## tracking

when enabled per newsletter: open tracking via pixel, click tracking via redirect. per-delivery stats: open count, click count, first/last timestamps. aggregate: opens by subscriber, clicks by URL.