Documentation

Set up your domain, invite your team and integrate with your applications.

Getting started

  1. Create your workspace and confirm your email address (required before sending).
  2. Go to Admin → Domains, add your domain and follow the DNS wizard.
  3. Once the domain is verified, create mailboxes such as info@ or sales@ under Admin → Mailboxes.
  4. Invite employees under Admin → Team and assign them to mailboxes with the permissions they need.

DNS records explained

  • Ownership (TXT) at _orbit7-verification.yourdomain.com proves you control the domain. Nothing is verified until this record is visible in public DNS.
  • DKIM (TXT) lets receiving servers confirm that mail really came from your domain.
  • SPF (TXT) and return-path (MX) on the sending subdomain authorize our delivery provider and handle bounces.
  • MX records on your root domain route incoming mail to our receiving pipeline.
  • DMARC (TXT) at _dmarc.yourdomain.com tells receivers what to do with mail that fails authentication. Start with p=none, then move to quarantine once everything passes.

DNS changes usually appear within minutes but can take up to 48 hours. Use Check now in the wizard; pending domains are also re-checked automatically.

Receiving email

Incoming mail is received through Cloudflare Email Routing, so your domain's DNS must be hosted on Cloudflare. When you add a domain you can choose Managed DNS: we create the zone, show you two nameservers to set at your registrar, and then configure every record automatically. Domains on other DNS providers can send email, but cannot receive it.

Mail to an address that does not exist is rejected during delivery. Messages up to 25 MB are accepted, and plus-addressing (info+news@) is delivered to the base mailbox.

Team & permissions

Roles: the owner manages everything including admins; admins manage domains, mailboxes, members and billing; members only use the mailboxes assigned to them.

Per-mailbox permissions: read, send (new messages), reply, forward, delete (move to trash, delete forever) and manage folders. The Free plan supports full or read-only access; Pro and Business allow any combination.

Limits

Each plan limits domains, mailboxes, users, storage, emails per hour, day and month, recipients per email and attachment size. Limits are enforced on the server; reaching one returns a clear error. Recipients that hard-bounce or mark your mail as spam are added to your suppression list automatically.

Developer API

Available on plans with API access. Create keys under Admin → Developers. Keys are shown once; keep them secret. Scopes: emails:send, emails:read, domains:read, mailboxes:read, webhooks:manage.

Send an email

POST /api/v1/emails
Authorization: Bearer o7_live_...
Idempotency-Key: <unique-per-request>   (optional, recommended)

{
  "from": "[email protected]",      // or "mailboxId"
  "to": ["[email protected]", { "address": "[email protected]", "name": "B" }],
  "cc": [], "bcc": [],
  "subject": "Hello",
  "html": "<p>Hi</p>",                 // and/or "text"
  "attachments": [{ "filename": "a.pdf", "contentType": "application/pdf", "content": "<base64>" }]
}

202 Accepted
{ "id": "...", "status": "accepted", "providerMessageId": "..." }

accepted means the delivery provider took the message. Final states (delivered, bounced, complained, failed) arrive later via webhooks. Repeating a request with the same Idempotency-Key returns the original response; reusing a key with a different body returns 422.

Other endpoints

GET  /api/v1/emails/:id     status + event history   (emails:read)
GET  /api/v1/mailboxes      mailboxes this key can use (mailboxes:read)
GET  /api/v1/domains        domains + verification     (domains:read)
GET  /api/v1/webhooks       list endpoints             (webhooks:manage)
POST /api/v1/webhooks       { "url", "events": [] }    (webhooks:manage)

Errors return { "error": { "code", "message" } } with an HTTP status: 400 validation, 401 bad key, 402 plan limit, 403 forbidden or suspended, 404 not found, 429 rate or sending limit.

Webhooks

Events: email.sent, email.delivered, email.delayed, email.bounced, email.complained, email.failed, email.received. Failed deliveries are retried with exponential backoff for about a day.

Each request carries X-Orbit7-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + rawBody). Verify it and reject timestamps older than five minutes:

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}