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 - 401
  • domain_not_added / domain_not_verified / inbox_not_allowed / recipient_suppressed - 403
  • tier_limit - 403 (caps reached)
  • rate_limit_second / rate_limit_day / rate_limit_month - 429
  • delivery_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_KEY is 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 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.