Start here
Key foundational concepts worth reading before anything else.
- Quickstart — install, set a key, send. Under ten lines.
- Guardrails — scopes, recipient allowlists, CIDR IP restrictions, expiration dates, and approval mode.
- Contact Forms API — zero-backend HTML form endpoints with invisible bot honeypot traps and multi-framework embed snippets.
- Slack 1-Click Interactive Approvals — real-time Block Kit approval cards in team channels for human sign-off on autonomous sends.
- Inbound MX Routing — route customer replies to webhooks with ~85% token-saving clean Markdown.
- DMARC Reports & Deliverability Radar — native RFC 7489 aggregate XML ingestion and deliverability scorecard.
- Verification Studio — in-flight bounce shield with zero-debit guarantee and disposable domain detection.
- Ephemeral Testing Inboxes — waitForCode API for sub-150ms OTP extraction in Playwright and Puppeteer.
- Error Codes & Troubleshooting — complete catalog of 120 typed error envelopes.
- Domain setup — the four DNS records (SPF, DKIM, DMARC, MX), and what each one is for.
- Facts & Limits — canonical pricing, monthly limits, European datacenter hosting, and platform capabilities.
Five ways to connect
SadaSend provides five first-class ingress protocols depending on where your emails originate:
• Zero-Backend Contact Forms [LIVE]: Accept website form submissions directly in your inbox without writing backend code or running mail servers (https://api.sadasend.com/forms/submit). Works in HTML, Webflow, Framer, and React. Read the Contact Forms guide.
• Official Client SDKs [LIVE]: Zero-dependency client libraries (sadasend on npm & PyPI) are live with discriminated union results, auto-idempotency, and server-enforced guardrails. Install via npm install sadasend or pip install sadasend. Open-source repositories at github.com/sadasend. See the SDK guide.
• Model Context Protocol (MCP) [LIVE & FEATURED]: Native tools for AI coding assistants and autonomous agents (Google Antigravity, Cursor, Cline, Claude Desktop, Windsurf, Claude Code CLI, OpenCode, and ChatGPT/Codex). Officially listed on mcpservers.org and hosted at https://mcp.sadasend.com with streamable HTTP and 12 full email tools. Learn more in the MCP guide.
• RESTful API: Clean, predictable JSON over HTTPS for web applications, microservices, and serverless backends (https://api.sadasend.com/emails). Explore the API reference.
• SMTP Relay: Zero-code drop-in relay for WordPress, WooCommerce, Supabase Auth, Laravel, and standard mailers (smtp.sadasend.com:587). Read the SMTP relay guide.
Base URL and authentication
Every request is authenticated with a bearer token. Keys are environment-scoped and carry their own limits, IP allowlists, expiration dates, and persona tags.
POST https://api.sadasend.com/emails
Authorization: Bearer sada_live_sk_…
Idempotency-Key: 6f1c2a80-…
X-SadaSend-Agent: SupportBot
X-SadaSend-Source: agent
Content-Type: application/json
{
"from": "notifications@yourdomain.com",
"to": "user@example.com",
"cc": ["team@example.com"],
"bcc": ["archive@yourdomain.com"],
"subject": "Your receipt",
"html": "<p>Thank you for your order.</p>",
"agent_name": "SupportBot",
"source": "agent"
}API key modes and prefixes
The key prefix tells you its mode before the request hits the network:
• Live (`sada_live_sk_…`): Normal production sending. Dispatches mail directly to receiving mailboxes.
• Approval (`sada_agent_sk_…`): Human-in-the-loop mode for autonomous AI agents. Every send is held in pending_approval until reviewed and approved via Slack 1-Click buttons or in your dashboard.
• Test (`sada_test_sk_…`): Integration and CI mode. Validates schemas and templates without sending actual emails.
Channel & Agent Provenance
Every email accepted by SadaSend is automatically tagged with its ingress channel (mcp, sdk, api, smtp), sending persona source (agent, backend, automation, system), and optional agent identifier.
Provenance gives your team complete deliverability observability. You can filter the Email Activity log by agent name, inspect origin cards in the email detail drawer, and review agent deliverability health and bounce rates in your dashboard analytics.
/** Ingress channel & sending persona provenance */
export interface EmailProvenance {
/** Ingress protocol: 'mcp' | 'sdk' | 'api' | 'smtp' */
channel?: 'mcp' | 'sdk' | 'api' | 'smtp';
/** Sending persona source: 'agent' | 'backend' | 'automation' | 'system' */
source?: 'agent' | 'backend' | 'automation' | 'system';
/** Optional agent identifier (up to 128 characters) */
agent_name?: string;
}Rate limits and quota headers
Every API response emits standard rate limiting and quota headers, allowing clients and SDKs to track allowances in real time:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum recipient volume permitted in the key’s active rate limit window. |
| X-RateLimit-Remaining | Remaining recipient capacity in the active rate limit window. |
| X-RateLimit-Reset | Seconds until the current rate limit bucket resets. |
| Retry-After | Seconds to wait before retrying when throttled with HTTP 429. |
| X-Quota-Limit | Total monthly email quota included in your current account plan. |
| X-Quota-Used | Number of emails dispatched during the current monthly billing period. |
| X-Quota-Reset | ISO 8601 timestamp when your account plan’s monthly email quota resets. |
| X-Quota-Overage | Number of emails sent exceeding plan quota (billed at standard overage rate). |
The onboarding sandbox domain
Every new account can send immediately from onboarding.sadasend.com without setting up DNS records first.
To protect shared reputation across all customers, the sandbox has two guardrails: a lifetime limit of 100 messages per account, and a recipient jail. Mail from the sandbox may ONLY be dispatched to account team member email addresses or safe test sinks (*.test, example.com). Sends to external third-party recipients are refused with HTTP 403 sandbox_recipient_restricted.
Adding and verifying your own custom sending domain with SPF and DKIM DNS records lifts both restrictions completely.
Dedicated sending subdomains vs. apex domains
When onboarding a custom sending domain, mailbox providers (Google Workspace, Microsoft 365, Yahoo) strongly favor using a dedicated sending subdomain (e.g. mail.brand.com or send.brand.com) rather than your root corporate apex domain (brand.com).
Reputation Isolation: High-volume transactional and marketing emails are evaluated in a separate reputation container. A spam complaint or bounce on a promotional dispatch will not impair the day-to-day inbox placement of employee corporate email.
MX Record Safety: Your corporate apex domain already directs incoming mail to Google Workspace or Office 365. Using a dedicated subdomain prevents return-path collisions or MX routing conflicts.
Automatic DMARC Alignment: Under RFC 7489 relaxed alignment (aspf=r; adkim=r), subdomains automatically inherit your root domain DMARC policy from _dmarc.brand.com without publishing duplicate DNS records.
Errors
Errors return a machine-readable code and a human-readable message. Both are always present.
{
"error": "recipient_not_allowlisted",
"message": "Key allowlist is [@example.com]. Recipient is outside it.",
"docs": "https://www.sadasend.com/docs/errors#recipient_not_allowlisted"
}