Quickstart
Three steps to send your first email:
1. Get an API key
If you're an admin, create an account via the admin API. Otherwise, sign up via the website (when Stripe integration is live).
curl -X POST https://mail.sparked.network/admin/accounts \ -H "Authorization: Bearer adm_live_xxx" \ -H "Content-Type: application/json" \ -d '{"name":"Acme Inc","tier":"free"}' # → { "id": "...", "apiKey": "re_live_xxx", ... }
2. Add and verify a domain
curl -X POST https://mail.sparked.network/domains \ -H "Authorization: Bearer re_live_xxx" \ -H "Content-Type: application/json" \ -d '{"name":"acme.com"}' # Returns TXT records to publish: # sparked-verify.acme.com = <token> # sparked._domainkey.acme.com = v=DKIM1; k=rsa; p=<pubkey> # After publishing, verify: curl -X POST https://mail.sparked.network/domains/<id>/verify \ -H "Authorization: Bearer re_live_xxx"
3. Send
curl -X POST https://mail.sparked.network/emails \ -H "Authorization: Bearer re_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "from": "noreply@acme.com", "to": "user@example.com", "subject": "Welcome", "html": "<b>Hi!</b>" }'
Authentication
Every request requires a Bearer API key:
Authorization: Bearer re_live_xxx
Missing/invalid returns 401 invalid_api_key.
Errors
All errors use the same envelope:
{ "error": { "code": "domain_not_verified", "message": "..." } }Common codes:
missing_api_key/invalid_api_key- 401domain_not_added/domain_not_verified/inbox_not_allowed/recipient_suppressed- 403tier_limit- 403 (caps reached)rate_limit_second/rate_limit_day/rate_limit_month- 429delivery_failed- 500
Rate limits
Every response includes rate-limit headers:
X-RateLimit-Limit-Second: 15 X-RateLimit-Remaining-Second: 14 X-RateLimit-Limit-Day: 8000 X-RateLimit-Limit-Month: 80000
Check live usage at GET /usage.
Idempotency
POST /emails accepts an Idempotency-Key header. Same key within 24h returns the original response - no duplicate sends on retry.
Send email
POST /emails
Required: from, to, subject. At least one of html, text, or template_id.
{
"from": "Acme <noreply@acme.com>",
"to": ["user@example.com"],
"subject": "Welcome",
"html": "<b>Hi!</b>",
"text": "Hi!",
"cc": ["boss@acme.com"],
"bcc": ["audit@acme.com"],
"reply_to": "support@acme.com",
"headers": { "X-Order-Id": "42" },
"attachments": [{ "filename": "invoice.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQ..." }],
"template_id": "tpl_xxx",
"variables": { "name": "Alice" }
}Domains
GET /domains - list
POST /domains - add (returns TXT records to publish)
POST /domains/:id/verify - verify ownership + DKIM + SPF
POST /domains/:id/dkim/check - re-check DKIM
DELETE /domains/:id - remove
Inboxes
POST /domains/:id/inboxes - register local-part
DELETE /domains/:id/inboxes/:local - remove
Templates
GET /templates
POST /templates - create (Handlebars source)
GET /templates/:id
DELETE /templates/:id
Suppressions
GET /suppressions
POST /suppressions - manually block
DELETE /suppressions/:recipient - unblock
Webhooks
Configure via PATCH /me:
curl -X PATCH https://mail.sparked.network/me \ -H "Authorization: Bearer re_live_xxx" \ -H "Content-Type: application/json" \ -d '{"webhook_url":"https://api.acme.com/hook","webhook_secret":"whsec_xxx"}'
Events: email.sent, email.delivered, email.bounced, email.failed, email.opened, email.clicked.
Every webhook is HMAC-SHA256 signed (verify via X-Webhook-Signature header).
Messages
GET /messages/:id - status, open/click state, error
Events
GET /events?limit=50&offset=0 - recent delivery events
Usage
GET /usage - current rate-limit usage and tier limits
MCP Server
MCP server at POST /mcp. Streamable HTTP transport, JSON-RPC 2.0, protocol version 2024-11-05.
20 tools exposed. Full integration guide and client configs on the MCP page.
// Claude Desktop config { "mcpServers": { "sparked-mail": { "url": "https://mail.sparked.network/mcp", "headers": { "Authorization": "Bearer re_live_xxx" } } } }
API keys & rotation
GET /api-keys
POST /api-keys - create another (tier-capped)
DELETE /api-keys/:key
POST /api-keys/rotate - rotate current key
Subaccounts
GET /subaccounts
POST /subaccounts - create (parent only, inherits parent tier)
Inbound email (optional)
PATCH /domains/:id/inbound - enable
GET /domains/:id/inbound - status
Customer points their MX at Cloudflare Email Routing. Cloudflare → our Worker → POST to https://mail.sparked.network/inbound/:domain_id.
Setup instructions at GET /inbound/:domain_id/instructions - includes one-click Cloudflare Worker deploy URL.
SPF (optional, recommended)
POST /domains/:id/spf/check - check if SPF TXT record is published
Recommended value: v=spf1 -all (we send via rotating proxies, no fixed IPs).
SDKs
No SDK required - use fetch in any language. Examples:
Node.js
const res = await fetch('https://mail.sparked.network/emails', { method: 'POST', headers: { Authorization: `Bearer ${process.env.SPARKED_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ from: 'noreply@acme.com', to: 'user@example.com', subject: 'Hi', html: '<b>Hi</b>' }) })
Python
import requests res = requests.post( "https://mail.sparked.network/emails", headers={"Authorization": f"Bearer {os.environ['SPARKED_API_KEY']}"}, json={"from": "noreply@acme.com", "to": "user@example.com", "subject": "Hi", "html": "<b>Hi</b>"} )
cURL
curl -X POST https://mail.sparked.network/emails \ -H "Authorization: Bearer $SPARKED_API_KEY" \ -H "Content-Type: application/json" \ -d '{"from":"noreply@acme.com","to":"user@example.com","subject":"Hi","html":"<b>Hi</b>"}'
Admin API
Protected by ADMIN_KEY env var.
POST /admin/accounts - create account
GET /admin/accounts - list
PATCH /admin/accounts/:id - update tier/name/email
DELETE /admin/accounts/:id
GET /admin/tiers - built-in tier definitions
Custom plans
POST /admin/plans - create custom plan with any limits/price
GET /admin/plans
PATCH /admin/plans/:id
DELETE /admin/plans/:id
Assign to account via tier: "custom:<plan_id>" in create/update account calls.
Security
Sparked Mail is built with a security-first design. The full security practices are on the Security page. Summary:
- Authentication: Bearer tokens (SHA-256 + pepper at rest), per-IP rate limiting on auth endpoints, bruteforce lockout after 5 failures in 15 min.
- In transit: HTTPS only. HSTS enabled with 1-year max-age on HTTPS deployments.
- At rest: AES-256-GCM for DKIM private keys (when
ENCRYPTION_KEYis set). API keys and PII (IP, User-Agent) hashed with SHA-256 + per-deployment pepper. - Headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy, Permissions-Policy.
- Webhooks: HMAC-SHA256 signed via
X-Webhook-Signature. - Anti-abuse: honeypot fields on registration, alt-account detection, audit logging of admin actions, automatic suppression lists.
The /health endpoint exposes the current proxy pool size, account count, and cache sizes for live monitoring.
security.txt
We publish a RFC 9116 security.txt file at the well-known location:
GET /.well-known/security.txt
This file contains the contact URL for vulnerability reports, our PGP key fingerprint (for encrypted reports), our disclosure policy, and the URL of this Security page. Security researchers should consult it before reporting.
Example response:
Contact: https://mail.sparked.network/contact?category=security Expires: 2026-12-31T23:59:59.000Z Preferred-Languages: en Canonical: https://mail.sparked.network/.well-known/security.txt Policy: https://mail.sparked.network/security Acknowledgments: https://mail.sparked.network/security#disclosure
To report a vulnerability, use our contact form. PGP-encrypted reports are preferred - the current fingerprint is in the security.txt file. We respond within 48 hours and credit reporters in our Hall of Fame (with permission). See the vulnerability disclosure section.
Terms, Privacy, and Legal
- Terms of Service - acceptable use, billing, retention, liability, governing law.
- Privacy Policy - data controller, what we collect, GDPR/CCPA rights, cookies, subprocessors.
- Security page - full security practices and subprocessor list.
Sparked Mail is privacy-first. We do not publish a physical address for correspondence and we do not request one from our users. Use our contact form for all inquiries.