REST API reference

Use the Smailor API to provision addresses, send email from verified domains,
submit contact forms into a shared inbox, and inspect domain reputation. This
reference separates API-key endpoints from browser-session endpoints so you can
choose the correct authentication model.

Messages sent through the API count toward the authenticated account's plan and
safety limits.

Before you start

You need:

• a Smailor account with API access;
• an API key created in Settings → API;
• a verified custom domain for mailbox provisioning and outbound sending;
• a server-side environment variable or secret manager for the API key;
• a recipient address you control for the first delivery test.

Never embed a Smailor API key in browser JavaScript, a mobile application bundle,
a public repository, or a support screenshot. The key grants account-level
access and is shown in full only when it is created.

Request flow

Your backend
    |
    +--> Authorization: Bearer 
    |
    v
Smailor API --> validate account, domain, limits, and reputation
    |
    +--> 2xx: request accepted
    +--> 4xx: change the request or account configuration
    `--> 5xx: temporary failure; retry conservatively

Base URL

Use the origin of the Smailor instance:

Examples below use production. Do not send production credentials to a local or
untrusted origin.

Authentication

Send one of these headers on every API-key request:

Authorization: Bearer YOUR_API_KEY

or:

X-API-Key: YOUR_API_KEY

Prefer the standard Authorization header unless an intermediary strips it.
Treat a 401 unauthorized response as a key/configuration problem; creating
automatic retries will not fix an invalid credential.

Scopes

A key carries a set of scopes and each endpoint asserts the one it needs. Grant
the narrowest set that works: a key that only reads domains cannot be turned into
a key that sends if it leaks.

Scopes are per resource and verb class rather than per endpoint, so an endpoint
added to a resource you already granted never invalidates a deployed key.

A request whose key lacks the scope is refused with 403 insufficient_scope, and
the body names both what was required and what the key holds:

{
  "error": "insufficient_scope",
  "message": "This API key is missing the \"focus:read\" scope.",
  "requiredScope": "focus:read",
  "grantedScopes": ["domains:read"]
}

Retrying will not fix it — issue a key with the scope. Keys created before scopes
existed carry none in storage and are treated as unrestricted; re-issue them
rather than relying on that.

smtp:send is deliberately not in this vocabulary: it belongs to an SMTP
credential typed into a mail client and cannot be granted to an HTTP key. Same
for pop3:read and imap:read. Those are issued in the dashboard under
Settings → Mail client access, and are never interchangeable with a key.

Recommended integration flow

1. Add and verify a custom domain.
2. Call GET /api/v1/domains and require the expected domain to be verified.
3. Create member addresses with POST /api/v1/mailboxes when needed.
4. Send a single controlled message with POST /api/v1/send.
5. Confirm receipt and authentication at the destination mailbox.
6. Handle documented 4xx responses explicitly and retry only temporary
   failures.
7. Monitor bounce and complaint trends before increasing volume.

Endpoint: List Domains + Reputation

GET /api/v1/domains

Returns all custom domains in your account with:

• Verification state (verified)
• 30-day sends, bounces, complaints
• Reputation status (healthy, watch, blocked)
• Recommendation message

Example

curl "https://smailor.com/api/v1/domains" \
  -H "Authorization: Bearer sk_smailor_..."

Endpoint: Create Mailbox (White-Label)

POST /api/v1/mailboxes

Content-Type: application/json

JSON body

Example

curl -X POST "https://smailor.com/api/v1/mailboxes" \
  -H "Authorization: Bearer sk_smailor_..." \
  -H "Content-Type: application/json" \
  -d '{
    "localPart": "john-doe",
    "domain": "mailer.yourhost.com",
    "displayName": "John Doe"
  }'

Reputation Guard

Mailbox creation is automatically blocked when domain reputation is too risky:

• blocked status => API returns 409 domain_reputation_blocked
• Prevents large-scale onboarding on unhealthy domains
• Helps protect IP/domain reputation for all tenants

Endpoint: Send Email

POST /api/v1/send

Content-Type: application/json

JSON body

At least one of text or html must be non-empty.

For marketing or subscribed mail, supply both email headers in the JSON body:

{
  "headers": {
    "List-Unsubscribe": "",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  },
  "trackOpens": false
}

The HTTPS URL must identify the recipient and list and accept Gmail's POST
without a login or confirmation. Smailor passes these headers to its outbound
transports and signs both when Smailor performs DKIM signing. If you use your
own SMTP or API provider, confirm its received DKIM h= list includes both
headers. Other email headers are rejected with 400 invalid_headers rather
than silently ignored. A sender name comes from the sending address's Sender
name setting; the API from field only selects the address.

Example

curl -X POST "https://smailor.com/api/v1/send" \
  -H "Authorization: Bearer sk_smailor_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Welcome",
    "text": "Your mailbox is now active."
  }'

Endpoint: Focus Board

GET /api/v1/focus

Scope: focus:read. The attention board as data — what Focus decided a human
should look at, in the same order the dashboard shows it. Cards are always scoped
to the key's owner.

Read-only by design. There is no endpoint to dismiss or reprioritise a card:
an integration that could would make the board disagree with what the team
actually did, and the board's value is that it is trustworthy at a glance.

Query parameters

Success response

{
  "generatedAt": "2026-09-26T08:15:00.000Z",
  "total": 12,
  "summary": { "do_now": 3, "needs_attention": 5 },
  "sections": { "do_now": [ { "ticketId": "…", "subject": "…" } ] }
}

503 unavailable means Focus is not enabled on the account — not a transient
error, so do not retry it on a loop.

Endpoint: Focus Verdict for One Conversation

GET /api/v1/focus/conversations/:id

Scope: focus:read. Covers both the priority and the risk verdict for a single
conversation. An id from another workspace reads as 404 not_found, the same as
an id that does not exist.

The response carries priority (level, section, state, score, reasonCodes,
whyHere, suggestedAction, confidence), risk (level, score, factors), and
the surrounding facts: waitingMinutes, followUpCount, ownerId,
handlingTime, promise, spamStatus, securityRisk, updatedAt.

reasonCodes are machine-stable and safe to branch on. whyHere is the sentence
a human reads and is not a stable contract.

Endpoint: Focus Promises

GET /api/v1/focus/promises

Scope: focus:read. Commitments detected in what your team wrote — "I'll get back
to you tomorrow" — with the deadline the wording implied.

Each entry carries id, conversationId, subject, senderEmail, promise,
promiseText, dueAt, needsReview, status, overdueMinutes, confidence,
detectedBy and createdAt.

dueAt is null when the wording carried no deadline. It is never a guess,
so treat null as "no deadline stated" rather than substituting one — and
needsReview marks the ones a human should confirm.

Endpoint: Contact Widget Submit

POST /api/widget/submit

Content-Type: application/json

Powers the embeddable contact forms generated in Settings -> Widgets. A website visitor fills in a form, and the message lands in your Smailor inbox as a new ticket from that visitor.

Unlike /api/v1/send, this endpoint delivers inbound to your own inbox, so to only has to be an active address on your account — a verified custom domain is not required.

Two ways to authenticate

A publishable key is created per address in Settings / Widgets / Contact forms. It can only deliver into that address, can be restricted to your websites, and is rate-limited to 10 submissions per 10 minutes per visitor IP. See the widgets guide for the full model, and for the live chat widget, which is built on the same keys.

JSON body

Attachments

Each entry of attachments is an object:

Default limits — configurable per deployment:

The widget limits are always clamped to the mailbox-wide ones (ATTACHMENT_MAX_PER_FILE_MB,
ATTACHMENT_MAX_PER_TICKET_MB), and the whole request must still fit under BODY_SIZE_LIMIT.
Base64 inflates payloads by roughly one third, so budget accordingly.

Accepted file types. Documents (PDF, Office, OpenDocument, RTF, TXT, CSV, Markdown, JSON,
XML), images, audio, video and archives. Executables, scripts and active web content are
refused. The declared mimeType is only a hint: the file is re-identified from its magic bytes
before it is written to disk, so renaming an executable does not get it through.

Example

curl -X POST "https://smailor.com/api/widget/submit" \
  -H "Authorization: Bearer sk_smailor_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from": "[email protected]",
    "name": "Jane Doe",
    "subject": "Question about pricing",
    "message": "Hi, do you offer annual billing?"
  }'

With an attachment:

curl -X POST "https://smailor.com/api/widget/submit" \
  -H "Authorization: Bearer sk_smailor_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"to\": \"[email protected]\",
    \"from\": \"[email protected]\",
    \"subject\": \"Invoice problem\",
    \"message\": \"The total on this invoice looks wrong.\",
    \"attachments\": [{
      \"filename\": \"invoice.pdf\",
      \"mimeType\": \"application/pdf\",
      \"contentBase64\": \"$(base64 -w0 invoice.pdf)\"
    }]
  }"

From a browser, read the file with FileReader.readAsDataURL and send everything after the
comma — that is exactly what the generated Settings → Widgets contact-form snippet does:

const toAttachment = (file) =>
  new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = String(reader.result);
      resolve({
        filename: file.name,
        mimeType: file.type || undefined,
        contentBase64: result.slice(result.indexOf(',') + 1),
      });
    };
    reader.onerror = () => reject(new Error(`Could not read ${file.name}`));
    reader.readAsDataURL(file);
  });

const attachments = await Promise.all([...fileInput.files].map(toAttachment));

Success response

{ "ok": true, "messageId": "", "attachments": 1 }

attachments is the number of files accepted for the ticket.

Errors

Attachment errors carry a human-readable message naming the offending file, plus a limits
object with the effective maxCount, maxPerFileBytes and maxTotalBytes — show it to the
visitor as-is:

{
  "error": "attachment_too_large",
  "message": "\"screenshot.png\" exceeds the 5 MB per-file limit.",
  "limits": { "maxCount": 3, "maxPerFileBytes": 5242880, "maxTotalBytes": 10485760 }
}

CORS

The endpoint answers OPTIONS preflight and allows cross-origin POST, so it can be called from your website's front-end. Restrict the allowed origins with the API_CORS_ORIGIN or API_CORS_ALLOWLIST environment variables (default: *).

Keep your API key server-side

Your API key grants full access to your account, not just widget submissions. Pasting it into front-end JavaScript makes it readable by any visitor via page source or the network tab, and reusable to send mail in your name.

For production, put the key behind your own server and have the browser call your endpoint instead:

// your-server/contact  →  proxies to Smailor with the key from an env var
const upstream = await fetch('https://smailor.com/api/widget/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.SMAILOR_API_KEY}`,
  },
  body: JSON.stringify({ to: RECIPIENT, from: visitorEmail, subject, message, attachments }),
});

If you forward attachments through your own server, raise its body-size limit too — Express
defaults to 100 KB (app.use(express.json({ limit: '12mb' }))).

Set the recipient (to) on your server too — never from the request body — otherwise the endpoint lets anyone send mail to any of your addresses.

Customer SMS Webhooks

Configure customer webhook URLs in Settings → API keys → Customer webhooks. Each endpoint can opt into sms.sent, sms.delivered, sms.failed, and sms.received independently of inbound.ticket_created. Existing endpoints continue to receive ticket events until you turn that checkbox off. SMS events require the Telecom add-on and SMS to be enabled.

The endpoint receives an HTTPS POST with JSON. For example:

{
  "event": "sms.delivered",
  "occurred_at": "2026-10-04T12:00:00.000Z",
  "message": {
    "id": "11111111-1111-4111-8111-111111111111",
    "ticket_id": null,
    "contact_id": null,
    "direction": "outbound",
    "status": "delivered",
    "to": "+33612345678",
    "from": "Smailor",
    "segments": 1
  }
}

sms.failed adds message.error_code; sms.received adds message.body and message.in_reply_to (the outbound SMS ID). Outbound message text and provider IDs are not included. A 2xx response acknowledges a delivery. Smailor retries other responses and timeouts up to eight times with exponential backoff. Delivery is at least once, so deduplicate using the stable X-Smailor-Delivery header. X-Smailor-Event and X-Smailor-Webhook-Id identify the event and endpoint. If a signing secret is configured, verify X-Smailor-Signature: sha256=<hex> as HMAC-SHA256 of the raw request body.

Campaigns can be launched from Settings → SMS → SMS campaigns, or with POST /api/v1/sms/campaigns using the sms:campaigns:write scope and an Idempotency-Key header. The Telecom plan must have campaigns enabled. The JSON body contains name, templateId (an approved template, see Templates below), recipients (1–500 E.164 numbers), and optionally variables, senderId and replyEnabled. Campaigns use the ordinary per-message queue; recipients are queued in batches by the campaign dispatcher, normally within a minute. GET /api/v1/sms/campaigns and GET /api/v1/sms/campaigns/{id} use sms:campaigns:read and return current counts and recipient status. The API returns 202 once the campaign and recipient list are saved.

Subscribe to campaign.started, campaign.completed, and campaign.failed on the same customer webhook endpoints. A campaign completes when every recipient has either been accepted by the SMS provider or definitively failed. campaign.failed means no recipient was accepted by the provider. Later delivery receipts continue to update the campaign's delivered and failed counts. Campaign webhook bodies include event, occurred_at, and campaign with id, status, total, sent, delivered, and failed.

SMS refusals worth handling

Every SMS goes through the same content check as Smailor email before anything is counted. A refused SMS uses no quota and no credit.

Templates

A template is fixed text with blanks, such as Bonjour {{first_name}}, votre rendez-vous est confirme le {{date}} a {{time}}. The blanks are a fixed list, each with a type: first_name, last_name and company (text up to 40 characters, no link), date, time, order_id and reference (letters, digits, -, _, /), amount, code (4 to 10 letters or digits, for sign-in codes) and url (an https link on a domain verified on your account). Most of a template must be fixed text.

POST /api/v1/sms/templates with sms:send and { "name", "body" } answers 201 with status approved when Smailor's content check finds nothing, or pending while Smailor checks it. GET /api/v1/sms/templates with sms:read lists them. Send from an approved template with POST /api/v1/sms/send and { "to", "templateId", "variables": { "first_name": "Marie", ... } } instead of message; every blank must be filled. The rendered text is checked like any SMS. Campaigns are always sent from an approved template: POST /api/v1/sms/campaigns takes templateId and variables (the same values for every recipient) and refuses a free message with template_required.

Asking for a country

POST /api/v1/sms/destination-requests with the sms:send scope asks Smailor to open a country. The JSON body has country (ISO 3166 code such as DE), useCase (10 to 500 characters) and optionally monthlyVolume. A second request for the same country updates the first and answers 200; a new one answers 201. At most 10 requests per account wait for an answer at a time. GET /api/v1/sms/destination-requests with sms:read lists them with their status (open, planned, added, declined) and Smailor's note. The account owner also gets an email when a country is added or declined.

Common Errors

Applies to /api/v1 endpoints.

403 and 503 are decisions, not transient failures: retrying either without
changing the key or the plan produces the same answer.

Best Practices for Reputation Safety

• Use double opt-in for new senders
• Warm up new domains gradually
• Stop onboarding when bounce/complaint rates increase
• Separate transactional and marketing traffic per domain
• Monitor domain-level events daily

For bulk marketing or subscription mail to personal Gmail accounts, see
one-click unsubscribe requirements.
The send API accepts the RFC 8058 unsubscribe header pair; customers must host
the unsubscribe endpoint and suppress opted-out recipients. Smailor's own
outreach workflow handles its own opt-outs.

Reply Templates (Web Session API)

These routes power the in-app template editor and ticket composer. They authenticate with the same session as the dashboard (browser cookies after login), not with Authorization: Bearer sk_… keys used for /api/v1.

Use cases: building automation around your own logged-in browser session, internal tools same-origin with Smailor, or understanding what the UI calls.

Create template (POST /api/templates)

Content-Type: application/json

Placeholders

Subject and HTML may use {{variable}} tokens. Common keys: customer_name, customer_email, ticket_id, subject, group_name, sender_name, company_name, date. Unknown keys are left unchanged at render time.

Example (session required — copy your logged-in Cookie header from the browser on your own origin)

curl -X POST "https://smailor.com/api/templates" \
  -H "Content-Type: application/json" \
  -H "Cookie: " \
  -d '{
    "name": "Thanks",
    "subject": "Re: {{subject}}",
    "body_html": "
Hi {{customer_name}},
Thanks for your message.
"
  }'

Errors mirror other JSON APIs: 401 when not signed in, 400 for validation or template quota, 403/404 when listing with ticketId you cannot access.

See Also

• Domain delivery statistics
• Add a new domain
• DKIM setup
• Email setup and deliverability

Outbound conversation capacity

Prices are in EUR, excluding VAT. Solo is annual-only. Annual Starter, Pro and Business cost ten monthly payments. Usage allowances renew every calendar month, including on annual plans.

Available on every plan, including Free. Packs are stackable and always billed monthly.

A new conversation started by you counts as one outbound conversation. Replies don't count.

POST /api/v1/send starts a new conversation and consumes one outbound unit when accepted into the queue. Retries with the same idempotency key do not consume another unit. Existing-thread replies and SMTP messages with a valid owned thread reference do not consume another unit. remaining reports available outbound capacity, including paid packs, for the UTC calendar month. 429 send_limit_reached means no capacity for new conversations; existing replies still work. Rate-limit errors are independent and may affect replies too.

Usage is shared across the account and its team, including your own sending provider. Packs do not grant paid API access on Free. See plans and outbound packs for the complete counting, reset and billing rules.