API Reference

tinysend REST API Reference

Base URL: https://api.tinysend.co/v1

All requests require Authorization: Bearer YOUR_API_KEY. Create API keys in your dashboard.

POST/emails

Send an email

Send a single transactional email. Supports HTML and plain text, attachments, reply-to, and idempotency keys for safe retries.

Request body

Field	Type	Required	Description
from	string	Yes	Sender address. Must be from an authenticated domain.
to	string \| string[]	Yes	Recipient address(es). Max 50 per request.
subject	string	Yes	Email subject line.
html	string	No*	HTML email body. Required if `text` is not provided.
text	string	No*	Plain text fallback. Required if `html` is not provided.
reply_to	string	No	Override the reply-to address.
idempotency_key	string	No	Unique key to prevent duplicate sends. Same key = same result within 24h.
tags	object	No	Key-value metadata for filtering analytics (max 10 tags).

Example request

curl -X POST https://api.tinysend.co/v1/emails \
  -H "Authorization: Bearer ts_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Verify your email",
    "html": "<p>Click <a href=\"https://yourapp.com/verify?token=abc\">here</a> to verify.</p>",
    "text": "Verify at: https://yourapp.com/verify?token=abc",
    "idempotency_key": "verify-user-123",
    "tags": {
      "type": "transactional",
      "user_id": "user_123"
    }
  }'

Response

{
  "id": "msg_01HXYZ...",
  "status": "queued",
  "created_at": "2026-03-31T12:00:00Z"
}

GET/emails

List emails

Returns a paginated list of sent emails. Filter by status, date range, or tags.

Query parameters

Parameter	Default	Description
limit	20	Number of results (max 100).
cursor	—	Pagination cursor from the previous response.
status	—	Filter by: `queued`, `sent`, `delivered`, `bounced`, `failed`.

GET/emails/:id

Get email status

Retrieve the current delivery status of a sent email by message ID.

curl https://api.tinysend.co/v1/emails/msg_01HXYZ... \
  -H "Authorization: Bearer ts_live_xxxxxxxxxxxx"

HTTP status codes

Code	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
422	Unprocessable — domain not authenticated or suppressed recipient
429	Rate limited — see `Retry-After` header
500	Server error — safe to retry with exponential backoff

Webhooks

tinysend POSTs delivery events to your webhook URL. Configure endpoints in your dashboard under Settings → Webhooks.

Event types

email.sent

Email accepted and queued for delivery.

email.delivered

Delivery confirmed by receiving server.

email.bounced

Permanent delivery failure (hard bounce).

email.soft_bounced

Temporary delivery failure (soft bounce).

email.opened

Recipient opened the email.

email.clicked

Recipient clicked a tracked link.

email.spam_reported

Recipient marked email as spam.

email.unsubscribed

Recipient unsubscribed via list-unsubscribe.

Example payload

{
  "event": "email.delivered",
  "message_id": "msg_01HXYZ...",
  "timestamp": "2026-03-31T12:00:05Z",
  "to": "[email protected]",
  "tags": { "type": "transactional", "user_id": "user_123" }
}

Rate limits

The API is rate limited per API key. When you hit the limit, the response includes a Retry-After header with the number of seconds to wait.

100

requests/second

1,000

free plan monthly

∞

paid plan (usage-based)

Need help?

Check the docs home or read language-specific guides in the blog.

Get your API key