tinysend has a REST API at api.tinysend.com. Everything you can do in the dashboard you can do over HTTP — create newsletters, manage subscribers, send broadcasts, configure your sender.

The full machine-readable spec lives at api.tinysend.com/v1/openapi.json. This page is the human version.

Authentication

Every request needs a bearer token:

Authorization: Bearer sk_...

Create a token in your account settings, or — if you’re an agent — register for one with no human in the loop. See the agent quickstart.

Conventions

JSON in, JSON out, snake_case keys
a single item returns the object directly; a collection returns an array
a newsletter and its subscribers, posts, and sender are newsletter-scoped (under /v1/lists/:id); contacts, emails, stats, webhooks, invites, settings, usage, and billing are account-scoped
errors look like { "error": { "code": "...", "message": "..." } }
cursor-based pagination via the Link header
rate limit and discovery links are in the response headers

Endpoints

Newsletters (the audience container; the path is /v1/lists):

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

Subscribers:

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

Posts:

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

Transactional email (single recipient, sent from a mailbox) — see transactional:

POST   /v1/emails                         send one email
GET    /v1/emails/:id                     email status

Mailbox emails (conversational send/reply from a mailbox):

GET    /v1/mailboxes/:id/emails           list emails in a mailbox
POST   /v1/mailboxes/:id/emails           create outbound email
GET    /v1/mailboxes/:id/emails/:eid      email detail
PATCH  /v1/mailboxes/:id/emails/:eid      update email status

Sender domain (one per list; /domain is a deprecated alias of /sender):

GET    /v1/lists/:id/sender               status + DNS records
PUT    /v1/lists/:id/sender               set up
POST   /v1/lists/:id/sender/check         verify DNS
DELETE /v1/lists/:id/sender               remove

Usage:

GET    /v1/usage                          current period usage and limits

Errors

unauthorized      401   missing or invalid token
forbidden         403   no access to this resource
not_found         404   resource doesn't exist
validation_error  422   invalid request body
limit_exceeded    402   monthly email limit reached
rate_limited      429   too many requests

Rate limits

60 requests per minute per token. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Questions?

Contact us at hi@tinysend.com.