Docs / Start here

Concepts

Workspace

A workspace holds members, API keys, provider connections, domains, templates, contacts, campaigns, the inbox and logs. Everything below belongs to one workspace.

Connection

A connection is one provider account you own, with its credentials encrypted using ONESEND_SECRET (AES-256-GCM). The dashboard lists connections under Sending providers. A connection has:

  • Status: active, paused or error (for example a bad or revoked key, or repeated failures).
  • Quota: daily, monthly and per-second limits, and where they came from: detected (read from the provider API), default (the known free tier), manual (set by you) or learned (OneSend saw the provider refuse sends at that level).
  • Health: a score from 0 to 100 based on recent results. A circuit breaker opens after a burst of provider errors and skips that connection for a while.
  • Use for campaigns (allowBroadcast): many free plans do not allow marketing email. Campaign email (type broadcast) routes only to connections where this is on.

Use one account per provider. Opening several free accounts with the same provider to multiply the quota breaks most providers' terms and can get the accounts closed. OneSend does not support that.

Routing policy

A routing policy is an ordered list of connections, plus optional rules, that decides which provider carries each email. The dashboard edits policies under Routing; the API uses /v1/policies.

{
  "name": "Default",
  "strategy": "priority",
  "steps": [
    { "connectionId": "con_resend…", "dailyCap": 99 },
    { "connectionId": "con_brevo…", "dailyCap": 295 },
    { "connectionId": "con_cloudflare…" }
  ],
  "rules": [
    {
      "when": { "recipientDomain": ["gmail.com", "googlemail.com"] },
      "steps": [{ "connectionId": "con_brevo…" }, { "connectionId": "con_resend…" }]
    }
  ],
  "fallback": "queue_until_reset",
  "messageTypes": ["transactional", "broadcast"]
}
  • strategy: priority (in order), weighted (by each step's weight) or round_robin.
  • steps: each step has a connectionId, and optionally dailyCap (leave headroom under the provider's limit), weight and enabled.
  • rules: the first rule whose when matches replaces steps for that email. when can match recipientDomain, tag, type and fromDomain.
  • fallback: what happens when every candidate is exhausted. queue_until_reset schedules the email for the next quota reset; fail marks it as failed.

POST /v1/route/preview (also onesend and the MCP tool route_preview) shows which connection would be used now and why the others are skipped.

Routing by sending domain

Before the policy order applies, the From domain filters the connections. When the From domain is a domain of the workspace, a connection is used only if the domain is verified there (or the provider needs no per-domain verification, such as SMTP), and only if it is among the domain's allowed providers when the domain has a list. A forced provider is held to the same rules. When nothing is left, the email fails with no_provider_for_domain instead of going through a provider that would reject it or send it unauthenticated. See Which providers send for a domain.

Failover rules

OutcomeExamplesWhat OneSend does
retry_next5xx response, timeout, provider outage, daily or monthly quota exhausted, revoked keyTries the next eligible connection
retry_same429 per-second rate limitWaits briefly and retries the same connection
recipient_fatalHard bounce, invalid mailbox, recipient suppressed at the providerStops. Does not fail over. Adds the address to the suppression list
config_fatalDomain not verified at this provider, sender not allowedSkips this connection and alerts you
no_provider_for_domainNo connection of the routing path may or can send for the From domainFails the email (422 when sending). Never picks another provider for that domain

Recipient errors never fail over: retrying a bad address on several providers would damage the reputation of every account involved.

Idempotency

POST /v1/emails and POST /v1/emails/batch accept an Idempotency-Key header (the SDK adds one automatically). A repeated key returns the original email instead of sending again. POST /v1/conversions accepts idempotencyKey in the body. When a provider call times out without a clear result, OneSend checks the message status before trying another provider, so a slow provider does not cause a duplicate.

Quotas

OneSend keeps its own counters per connection per day, in the provider's reset time zone, and corrects them from provider signals such as Resend's x-resend-daily-quota header or Brevo's account credits. The Dashboard page and GET /v1/analytics/quota show used and remaining capacity per provider and in total, and an estimate of when today's quota will run out.

Suppression list

One list per workspace, shared by every provider. It holds hard bounces, spam complaints, unsubscribes and manual entries. Suppressed recipients are removed before routing. An entry's scope is all, or broadcast for addresses that opted out of marketing only.

Events and tracking

Provider webhooks (delivered, bounced, complained, opened, clicked) are normalized into one event stream, which you can receive with webhooks. OneSend can also add its own open pixel and click tracking, so engagement is comparable across providers. Apple Mail Privacy Protection inflates opens; machine opens are flagged.

Tracking settings exist at three levels. An email's own tracking wins, then its From domain's settings, then the workspace defaults. Each domain can also have its own tracking subdomain. See Tracking per domain.

Sandbox mode

Two things never deliver email:

  • The Sandbox provider. Every new workspace includes a Sandbox connection in its default policy, so the first API call succeeds. It accepts every email and delivers none; the email shows status sent with provider sandbox. When you connect a real provider, Sandbox is turned off in the default policy. Sandbox can simulate outages, quota exhaustion and bounces to test failover.
  • Test API keys (os_test_…). Emails sent with a test key are stored with status sandboxed and never reach a provider. Use them in development and CI.