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,pausedorerror(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) orlearned(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 (typebroadcast) 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'sweight) orround_robin.steps: each step has aconnectionId, and optionallydailyCap(leave headroom under the provider's limit),weightandenabled.rules: the first rule whosewhenmatches replacesstepsfor that email.whencan matchrecipientDomain,tag,typeandfromDomain.fallback: what happens when every candidate is exhausted.queue_until_resetschedules the email for the next quota reset;failmarks 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
| Outcome | Examples | What OneSend does |
|---|---|---|
retry_next | 5xx response, timeout, provider outage, daily or monthly quota exhausted, revoked key | Tries the next eligible connection |
retry_same | 429 per-second rate limit | Waits briefly and retries the same connection |
recipient_fatal | Hard bounce, invalid mailbox, recipient suppressed at the provider | Stops. Does not fail over. Adds the address to the suppression list |
config_fatal | Domain not verified at this provider, sender not allowed | Skips this connection and alerts you |
no_provider_for_domain | No connection of the routing path may or can send for the From domain | Fails 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
sentwith providersandbox. 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 statussandboxedand never reach a provider. Use them in development and CI.