Skip to content

Developer Documentation & Email API Quickstart

Last updated 28 October 2026

Everything needed to send your first email, and to understand why the key you send it with matters.

SadaSend REST APIs, Port 587 ESMTP submission relay, hosted MCP tools for AI agents, and official zero-dependency TypeScript and Python SDKs are live in production. Every account receives 6,000 monthly transactional emails with strict server-enforced guardrails.

Start here

Key foundational concepts worth reading before anything else.

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.

HTTP
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.

TYPESCRIPT
/** 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:

HeaderDescription
X-RateLimit-LimitMaximum recipient volume permitted in the key’s active rate limit window.
X-RateLimit-RemainingRemaining recipient capacity in the active rate limit window.
X-RateLimit-ResetSeconds until the current rate limit bucket resets.
Retry-AfterSeconds to wait before retrying when throttled with HTTP 429.
X-Quota-LimitTotal monthly email quota included in your current account plan.
X-Quota-UsedNumber of emails dispatched during the current monthly billing period.
X-Quota-ResetISO 8601 timestamp when your account plan’s monthly email quota resets.
X-Quota-OverageNumber 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.

JSON
{
  "error": "recipient_not_allowlisted",
  "message": "Key allowlist is [@example.com]. Recipient is outside it.",
  "docs": "https://www.sadasend.com/docs/errors#recipient_not_allowlisted"
}