Get started

Getting started — five-minute setup

The shortest path from tenant just created to first transactional email in a Gmail inbox. Skim this once; bookmark it for the next teammate you onboard. For a longer walkthrough with screenshots, see New tenant — first 30 minutes.

1. Create a tenant + mint an API key (1 min)
2. Add a sending domain (1 min)
3. Publish SPF / DKIM / DMARC (2 min in DNS + ~2 min propagation)
4. Send your first email (30 sec)

1 · Create a tenant + mint an API key

Register at /register. The first 1,000 sends each month are free; no credit card. Once you're in, head to Settings → API keys and click Create key.

• Pick scope transactional:send for a smoke test — scope reference for the full list.
• Production keys are prefixed sb_live_. For integration tests and CI, mint a separate sb_test_ sandbox key — every send against a sandbox key is queued, observable in the dashboard, then dropped before it leaves the MTA. No reputation impact, no quota burn. (See W213 sandbox testing.)
• The key string is shown once. Copy it now or you'll need to issue a new one.

# Production
SENDBOLT_API_URL=https://api.sendbolt.io
SENDBOLT_API_KEY=sb_live_a1b2c3d4e5...

# Sandbox (W213) — sends are accepted, queued, then dropped
SENDBOLT_API_KEY=sb_test_a1b2c3d4e5...

2 · Add a sending domain

Open /dashboard/domains, click Add domain, enter the apex (e.g. acme.com). SendBolt auto-generates a 2048-bit DKIM keypair scoped to your tenant + domain and stores the private half encrypted at rest.

Why this matters (W174): SendBolt refuses to accept sends from a tenant with zero verified domains. The transactional/send endpoint returns 412 Precondition Failed with error="no_verified_domain"until the next step is complete. This is intentional: it stops a new account from polluting the shared IP pool's reputation before DNS authentication is in place.

3 · Publish SPF / DKIM / DMARC

The domain detail page shows four records to add at your DNS provider (Cloudflare, Route 53, Namecheap, etc.). Each row has a one-click copy button.

Click Verify after saving. The page polls every 30 seconds and turns green once all four resolve — usually within 2–5 minutes, occasionally up to 24 hours on a slow DNS provider.

Programmatic option (from your shell or a CI job):

# Trigger backend re-verification (idempotent)
curl -X POST "$SENDBOLT_API_URL/api/v1/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $SENDBOLT_API_KEY"

4 · Send your first email

Once at least one domain is verified the W174 gate lifts and you can hit /api/v1/transactional/send. The simplest body is { to, subject, body_text }:

curl -X POST "$SENDBOLT_API_URL/api/v1/transactional/send" \
  -H "Authorization: Bearer $SENDBOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@example.com",
    "from_email": "no-reply@acme.com",
    "subject": "Hello from SendBolt",
    "body_text": "It works.",
    "body_html": "<p>It <strong>works</strong>.</p>"
  }'

What a successful response looks like

{
  "ok": true,
  "data": {
    "message_id": "msg_01J7K8H6F2NX8Z3Y4WQ5T1A2B3",
    "status": "queued"
  }
}

Common non-200 shapes — see error reference for the full set:

• 412 no_verified_domain — W174 gate. Verify a domain (step 3) before this lifts.
• 402 quota_exceeded — monthly send-cap hit. Upgrade plan or wait for the 1st of the next month.
• 422 validation_error — required field missing. Response includes the field name in message.
• 429 rate_limited — burst limit hit (default 600 req/min on the send path). Honour Retry-After.

Marketing vs transactional

Transactional (/transactional/send) is for one-recipient, one-message sends triggered by user action — signup verification, password reset, receipts. Bulk / marketing sends go through Campaigns which adds per-recipient unsubscribe headers and consent enforcement:

• W198 — RFC 8058 List-Unsubscribe: every campaign send carries a List-Unsubscribe header plus a one-click List-Unsubscribe-PostURL so Gmail and Outlook can render a single-click unsubscribe button directly in the receiver UI. Your tenant's unsubscribe page hosts the post-back; SendBolt handles the suppression write.
• Marketing-stream gating: a recipient who's unsubscribed from marketing can still receive transactional sends (their password reset still works), but the campaign engine drops them automatically.

What next

• Wire a real signup flow: signup verification recipe
• See the full endpoint catalogue: API reference
• Automate from CI: sendbolt-cli & GitHub Action
• Receive replies (inbound): inbound webhook
• Going to launch >200 recipients? Warm-up guide first.