API guide
Send Your First Email in Minutes.
One authenticated request, JSON in and JSON out. This page covers the essentials; the full reference lives in your dashboard.
- JSON API
- Bearer API key
- Idempotency Keys
Quick Start
- 1
Verify Your Account Email
Sign up and confirm your email address.
- 2
Add and Verify a Domain
Add the DNS records shown in the dashboard. We check MX, SPF, DKIM and DMARC.
- 3
Create an API Key
Make a key with the send scope. It is shown once, so store it as a secret.
- 4
Call POST /v1/send
You get a 202 and a message id back. Delivery happens in the background.
Send an Email
Authenticate with Authorization: Bearer YOUR_API_KEY. Keys use the ts_live_ prefix.
cURL
curl -s -X POST "https://api.traffsite.com/v1/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"subject": "Your receipt",
"body": "Thanks for your order.",
"domain": "yourdomain.com"
}'Node.js
const res = await fetch("https://api.traffsite.com/v1/send", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.TRAFFSITE_API_KEY,
"Idempotency-Key": "order-1042-receipt",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "[email protected]",
subject: "Your receipt",
body: "Thanks for your order.",
domain: "yourdomain.com",
}),
});
const data = await res.json();Python
import os, requests
r = requests.post(
"https://api.traffsite.com/v1/send",
headers={
"Authorization": "Bearer " + os.environ["TRAFFSITE_API_KEY"],
"Idempotency-Key": "order-1042-receipt",
},
json={
"to": "[email protected]",
"subject": "Your receipt",
"body": "Thanks for your order.",
"domain": "yourdomain.com",
},
)
print(r.json())Request Fields
| Field | Required | Notes |
|---|---|---|
| to | Yes | One email address, up to 254 characters. |
| domain | Yes | A domain you have added and verified. |
| from | No | Must belong to one of your verified domains. |
| subject | No | Up to 500 characters, no line breaks. |
| body / html | No | Plain text up to 50,000 characters, or an HTML body. |
| template, variables | No | Send a saved template with up to 50 variables. |
| attachments | No | Up to 5 files, 2 MB each and 5 MB in total. |
| Idempotency-Key (header) | No | 1 to 128 characters. A retry with the same key does not send twice. |
Webhooks
Register an endpoint and receive a POST for message events: message.accepted, message.failed, message.bounced and message.complaint. Payloads never include the message body.
| Header | Value |
|---|---|
| X-Traffsite-Event | The event name, for example message.accepted. |
| X-Traffsite-Delivery | The delivery id. |
| X-Traffsite-Signature | t=TIMESTAMP,v1=HEX_HMAC, signed with your webhook secret. |
A failed delivery is retried up to 5 more times with growing delays. An endpoint that keeps failing is disabled automatically. You can have up to 5 endpoints.
Errors Worth Handling
| Status | Code | Meaning |
|---|---|---|
| 402 | INSUFFICIENT_CREDITS | No email credit left. Buy a pack. |
| 402 | INSUFFICIENT_BALANCE | The wallet cannot cover an attachment fee. Top up. |
| 422 | RECIPIENT_SUPPRESSED | The address is on your suppression list. Nothing is sent or charged. |
| 429 | DAILY_LIMIT_REACHED | The daily sending cap is used. It resets at 00:00 UTC. |