Build cold email workflows, automate campaigns, check deliverability, and manage your TuruMail account programmatically with our clean, JSON-first REST API.
TuruMail uses API key authentication with Bearer tokens. Every request must include your API key in the Authorization header.
Generate your API key from Dashboard → Settings → API Keys. Keys are prefixed with tm_live_ for production and tm_test_ for testing.
# Include in every request Authorization: Bearer tm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json
All API endpoints are relative to this base URL. We use semantic versioning — breaking changes increment the major version. The current stable version is v2.
| Plan | Requests/minute | Sends/hour | Batch size |
|---|---|---|---|
| Starter | 60 | 1,000 | 100 |
| Pro | 300 | 10,000 | 1,000 |
| Enterprise | 1,000 | 100,000 | 10,000 |
Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Required | Recipient email address |
| from | string | Required | Sender address (must be authenticated domain) |
| subject | string | Required | Email subject. Supports Spintax: {Hi|Hello|Hey} |
| body_html | string | Optional | HTML email body |
| body_text | string | Optional | Plain-text email body (recommended for cold email) |
| variables | object | Optional | Key-value pairs for template variables e.g. {"first_name":"Alex"} |
| smtp_id | string | Optional | Specific SMTP server ID to send from |
| track_opens | boolean | Optional | Enable open tracking (default: true) |
| track_clicks | boolean | Optional | Enable click tracking (default: true) |
curl -X POST https://api.turumail.com/v2/emails/send \ -H "Authorization: Bearer tm_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "to": "alex@prospect.com", "from": "sarah@yourcompany.com", "subject": "{Quick question|Hi there|Hey} about {{company}}", "body_text": "Hi {{first_name}},\n\nI noticed that {{company}} recently expanded into {{market}}...", "variables": { "first_name": "Alex", "company": "Acme Corp", "market": "enterprise SaaS" }, "track_opens": true }'
{
"success": true,
"message_id": "msg_01HXXXXXXXXXXXXXX",
"queued_at": "2026-06-17T10:32:01Z",
"status": "queued"
}
Send up to 10,000 personalized emails in a single request. Each recipient can have unique variables, subject lines, and even different sending addresses. TuruMail processes batches asynchronously and respects your IP warmup limits.
{
"campaign_id": "camp_01HXXX",
"from": "outreach@yourcompany.com",
"subject": "{Quick question|Thoughts on} {{company}}",
"body_text": "Hi {{first_name}}, ...",
"recipients": [
{
"to": "alex@acme.com",
"variables": {"first_name": "Alex", "company": "Acme"}
},
{
"to": "sarah@globex.com",
"variables": {"first_name": "Sarah", "company": "Globex"}
}
],
"options": {
"respect_warmup_limits": true,
"send_window": "business_hours",
"timezone": "America/New_York"
}
}
{ "email": "prospect@company.com" }
{
"email": "prospect@company.com",
"valid": true,
"result": "deliverable",
"is_disposable": false,
"is_catch_all": false,
"is_role": false,
"mx_records": true,
"smtp_check": true,
"score": 0.97
}
{
"score": 1.4,
"threshold": 5.0,
"verdict": "clean",
"checks": {
"spf": "pass",
"dkim": "pass",
"dmarc": "pass",
"content": "clean",
"links": "clean"
},
"flags": [
{ "rule": "SUBJ_ALL_CAPS", "score": 0.8, "description": "Subject contains uppercase words" }
]
}
All errors return a JSON body with a code and message field.
{
"success": false,
"error": {
"code": "INVALID_FROM_ADDRESS",
"message": "The from address domain is not authenticated. Please configure SPF and DKIM.",
"docs_url": "https://turumail.com/dkim-setup"
}
}
Official client libraries for the most popular languages. All SDKs are open source and available on GitHub.
TuruMail can send real-time webhook notifications to your endpoint for these events:
email.delivered — Email successfully delivered to the recipient's mail serveremail.opened — Recipient opened the email (pixel tracking)email.clicked — Recipient clicked a tracked linkemail.replied — Recipient replied to your emailemail.bounced — Email bounced (includes hard/soft bounce type)email.spam_complaint — Recipient reported email as spamemail.unsubscribed — Recipient clicked the unsubscribe linkblacklist.detected — Your sending IP was detected on a blacklistwarmup.limit_reached — Daily warmup volume limit reached for an IPAll webhooks are signed with an HMAC-SHA256 signature in the X-TuruMail-Signature header for verification.
Start with 1,000 free API calls. Upgrade as you grow. Full documentation and SDKs included.