From zero to first message in five minutes.
Below is the documentation hub: the quickstart for engineers in a hurry, the complete REST API reference, SMTP integration guides for applications that prefer SMTP, webhook setup, SDKs in six languages, deliverability fundamentals, migration guides from every major competitor, and an exhaustive error-code reference. Everything is versioned in our public git repository — pull requests welcome from customers who spot improvements.
- REST API
- https://api.osdomains.com/v2
- SMTP relay
- smtp.osdomains.com:587
- Customer portal
- app.osdomains.com
- Status
- status.osdomains.com
Send your first message in four steps.
- 1. Sign in to app.osdomains.com with your provisioned credentials.
- 2. Settings → API Keys → create a key with "send" scope. Copy it.
- 3. Add your sending domain in Domains and publish the SPF/DKIM/DMARC records we generate.
- 4. Run one of the code blocks below from your terminal or application. Done.
curl https://api.osdomains.com/v2/send \
-H "Authorization: Bearer $OSD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Welcome",
"html": "<p>Hello.</p>",
"text": "Hello."
}'
Expected response: { "id": "msg_...", "status": "queued" } within 80ms. The message lands in the recipient inbox within 1-3 seconds for major providers. If you do not get a response, check authentication (401) and DNS (domain not verified) before assuming a bug.
Eight sections, 45 pages.
Each section has its own URL and a sidebar of subpages. Search across all docs is at the top of the navigation. We aim for short, code-heavy pages rather than long narrative essays — if a page is taking more than 5 minutes to read, we probably need to split it.
Quickstart
Get sending in 5 minutes.
- Send your first message in 5 minutes
API key → curl → message delivered → webhook fired. End-to-end walkthrough.
- Provisioning your account (48-72h checklist)
DNS records (SPF, DKIM, DMARC), IP rDNS, domain verification, first warm-up step.
- Choosing your PoP
Latency map, capacity considerations, multi-PoP failover for Performance and Enterprise.
- Authentication: API keys vs OAuth2
When to use which, how to scope keys, rotation policy, never-commit checklist.
REST API
Complete reference for v1 and v2 endpoints.
- Send endpoint (POST /v2/send)
Single message and batch requests, idempotency keys, scheduling, custom headers.
- Templates endpoint
Create, list, update, delete email templates with Mustache and Handlebars syntax.
- Domains endpoint
Verify, list, manage sending domains. SPF/DKIM/DMARC status checks.
- IPs endpoint
List allocated IPs, warm-up status, rDNS hostname, pool assignment, request additional.
- Suppressions endpoint
Read, append, remove from suppression lists. Bulk operations, CSV import/export.
- Stats endpoint
Send/deliver/bounce/complaint counts. By domain, IP, time window, or template.
- Webhooks endpoint
Create, list, update webhook subscriptions. Event types, signing keys, retry policy.
- Pagination, rate limits, errors
Cursor-based pagination. 60K req/min default. Standardized error envelopes with retry hints.
SMTP integration
For applications that prefer SMTP over REST.
- SMTP relay credentials
Where to find them, how to rotate them, scope per environment.
- Ports and TLS
587 (STARTTLS), 465 (TLS), 2525 (legacy). TLS 1.3 default; TLS 1.2 grandfathered.
- X-OSD- custom headers
Tag messages with campaign IDs, customer IDs, template IDs for stats segmentation.
- Connection pooling guidance
Reuse connections; do not open one per message. Anti-noisy-neighbor protection.
- Sending from your CRM / marketing automation
Tested integrations with HubSpot, Salesforce Marketing Cloud, Customer.io, Klaviyo, Marketo.
Webhooks
Real-time event delivery to your endpoint.
- Event types
delivered, bounced, deferred, complained, opened, clicked, unsubscribed. Schema for each.
- Webhook signing (HMAC-SHA256)
How to verify the X-OSD-Signature header. Code samples in 6 languages.
- Retry policy and backoff
Exponential retry up to 30 minutes. 7-day replay buffer for missed deliveries.
- Idempotency and de-duplication
Use the X-OSD-Event-ID header to dedupe in your handler. Why some events deliver twice.
SDKs
Official client libraries in 6 languages.
- Node.js SDK (@osdomains/sdk)
npm install @osdomains/sdk. TypeScript-first, async/await, retries built-in.
- Python SDK (osdomains)
pip install osdomains. Sync and async clients (httpx). Pydantic models for type safety.
- Go SDK (github.com/osdomains/go-sdk)
Idiomatic Go, context-aware, generated from OpenAPI spec.
- Ruby SDK (osdomains gem)
gem install osdomains. Compatible with Rails 7+. ActiveModel-style.
- PHP SDK (osdomains/osdomains-php)
composer require osdomains/osdomains-php. PSR-7 compatible.
- Java SDK (com.osdomains:osdomains-java)
Maven Central. Java 11+. Reactive variant via Project Reactor.
Deliverability
Authentication, reputation, and inbox placement.
- SPF, DKIM, DMARC setup
The exact DNS records you publish, why each one matters, alignment checks.
- BIMI and VMC configuration
Logo design constraints, VMC chain validation, publishing in DNS.
- IP warm-up: how the automation works
Step sizes, engagement gates, how it adapts to your traffic pattern.
- Reading your DMARC reports
rua vs ruf, what to look for, common false alarms, when to escalate enforcement.
- Blacklist response playbook
Spamhaus SBL, CSS, ZEN, SORBS, Barracuda. Delisting steps, root-cause checklist.
- Gmail / Outlook / Yahoo specifics
Per-provider quirks: One Click List Unsubscribe, Microsoft SmartScreen, Yahoo dKIM lookup.
Migration guides
Coming from another provider.
- Migrating from AWS SES
How SES configuration sets translate, how to keep reputation, parallel-run pattern.
- Migrating from SendGrid
Template translation (Handlebars → OS Domains), Mail Settings parity, IP transfer options.
- Migrating from Mailgun
Domain verification, route configuration, suppression list import (CSV format).
- Migrating from SparkPost
Subaccounts, custom suppressions, event webhook payload differences.
- Migrating from Postmark
Server tokens, message streams (transactional/broadcast separation).
- Migrating from self-hosted Postfix or PowerMTA
Configuration parity, log import for historical visibility, IP reputation continuity.
Errors and troubleshooting
Common errors with concrete fixes.
- HTTP error codes reference
Every 4xx and 5xx code our API returns, with explanation and recommended retry.
- SMTP error codes (4xx, 5xx)
What "421 4.4.2" actually means, RFC vs real-world behavior, retry semantics.
- Bounce classifications
Hard, soft, spam-trap, content-rejected, mailbox-full, unknown-user. Mapping to actions.
- Webhook signature verification failures
Library upgrades, encoding differences, troubleshooting checklist.
- Rate-limit responses (429)
Headers we return, exponential backoff template, when to request a higher tier.
- Authentication errors (401, 403)
Expired keys, scope mismatch, IP allowlist issues.
Recipes you will reach for repeatedly.
Idempotent retries
Pass Idempotency-Key header so reruns within 24h return the original response, never duplicate.
Per-message tagging
Add X-OSD-Campaign-ID headers to segment stats by campaign without setting up subaccounts.
Webhook deduplication
Use X-OSD-Event-ID as your dedup key. We sometimes deliver twice; your handler should be idempotent.
Engagement-gated warm-up
Our scheduler ramps faster for high-engagement traffic. Send your best lists first during warm-up.
Batch sends
POST /v2/send accepts up to 1,000 recipients per request. Each gets a unique message ID for individual webhook events.
Handling 429 rate limits
Respect the Retry-After header. Pre-flight check via /v2/limits.
The docs are a living artifact. If you find a gap, tell us.
Documentation is one of those things that is never finished. If you spent 10 minutes hunting for an answer that we should have made obvious, write to [email protected] with the URL you wish existed and what it should say. We treat doc requests with the same priority as bug reports.