Build on Supromail with confidence.

Quickstart

Send your first message

Sign in, enable a channel, verify a sending domain, then queue a message with a scoped API key. Most teams are sending in under ten minutes.

Sign in

Supromail uses passwordless login. Enter your email address and choose Continue — there is no password field. We email a six-digit code; enter it to sign in.

The first time you sign in, Supromail asks for your name, your company or workspace name, and acceptance of the Terms of Service. Once you submit, your workspace is created and you are its owner.

Enable a channel

A new workspace starts with no arms enabled. An owner or admin turns on the channel they want from that arm's Settings page, or from Get started in the dashboard.

Verify a domain and send

1. Add a domain in Email → Domains and publish the DNS records Supromail returns. Full walkthrough →
2. Wait until the domain shows verified.
3. Create an API key in API Keys with the email:send scope. The secret is shown once — store it in your server-side secret manager.
4. Queue a message from your backend.

curl https://api.supromail.com/v1/email/messages \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome",
    "text": "Thanks for joining.",
    "idempotency_key": "welcome-2026-001"
  }'

const res = await fetch("https://api.supromail.com/v1/email/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPROMAIL_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    from: "[email protected]",
    to: "[email protected]",
    subject: "Welcome",
    text: "Thanks for joining.",
    idempotency_key: "welcome-2026-001"
  })
});

const { message_id, status } = await res.json();

import os, requests

res = requests.post(
    "https://api.supromail.com/v1/email/messages",
    headers={"Authorization": f"Bearer {os.environ['SUPROMAIL_API_KEY']}"},
    json={
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Welcome",
        "text": "Thanks for joining.",
        "idempotency_key": "welcome-2026-001",
    },
)

print(res.json())

A success returns 202 Accepted with { "message_id": "…", "status": "queued" }. Queued means accepted for sending: the message and its background send job were committed together, and a worker signs it with DKIM and delivers it. Use webhooks and the dashboard to observe Email and SMS outcomes; WhatsApp and Telegram also provide a per-message status endpoint.

Core concepts

These concepts carry most of the meaning in this documentation and in the dashboard.

Workspace

Your organisation's container. Domains, phones, linked numbers, bots, messages, API keys, and members all belong to exactly one workspace, and workspaces never see each other's data.

Project

A workspace namespace that groups operational resources and their activity, such as domains, API keys, mailboxes, phones, linked accounts, and bots. Projects organise resources; they do not create separate billing accounts or member permissions.

Arm

A channel — Email, SMS, WhatsApp, or Telegram — enabled per workspace, independently of the others.

Member & role

People in your workspace, each with a role (owner, admin, or member) that controls what they can do. See Members & roles.

Message

One email, SMS, WhatsApp, or Telegram message you sent. Each has a status that moves from queued toward a final outcome.

API key

A secret credential a program uses to send on your behalf. Scoped, optionally IP-restricted, and shown only once.

Webhook

A URL Supromail calls to notify your systems when something happens — a message delivered, an email bounced, mail received.

Projects

Use projects to keep the resources and activity for different applications, environments, customers, or teams distinct inside one workspace.

Billing, subscriptions, members, and roles stay at workspace level. A project is not a permission boundary: every member uses projects under their existing workspace role. Owners and admins manage project structure and resource moves.

Create and switch projects

1. Open Projects & resources from the account menu. Owners and admins can create a project when the workspace has capacity.
2. Review the current allowance before creating another project. Your Messaging plan sets the workspace's project limit; see Pricing to compare plans.
3. Use the project selector in the dashboard header, or choose Open on the Projects page, to switch the active project. The dashboard then loads data for that project.

New project-scoped resources are created in the active project. Check the selector before creating a domain, API key, mailbox, phone connection, bot, webhook, or other project-scoped configuration.

Move existing resources

1. Open Projects & resources, then choose Move existing resources. Only owners and admins can move resources.
2. Choose the resource type: API keys, mailboxes, SMS devices, Telegram bots, WhatsApp accounts, domains, or SMTP resources.
3. Select the resource and destination project. When offered, choose whether to include its related history.

Move the existing resource instead of recreating it. Related configuration follows the resource; history moves can take longer, so do not repeat the action while it is processing.

Channels overview

One dashboard and one API cover four channels. Each is enabled independently and has its own connected-resource limits.

SMS, WhatsApp, and Telegram are never charged per message — they run on hardware and accounts you own. Email is bounded by your plan's monthly allowance. See Pricing.

Email sending

Enable the Email arm, verify a sending domain, then send through the API. After that you manage your suppression list, watch the event log, and optionally wire up webhooks.

Verify a sending domain

You can only send from a domain you have proven you own. Verification also sets up DKIM — the cryptographic signature that keeps your mail out of spam folders.

1. In Email → Domains, add your domain, for example example.com.Admin Supromail generates a unique DKIM key and returns a set of DNS records.
2. Publish the four required TXT records at your DNS provider, plus an MX record if you want to receive mail.
3. Return to the dashboard and choose Verify. Supromail checks that the ownership, DKIM, SPF, and DMARC records are live, then flips the domain to verified.

Send an email

The from address must be on a verified domain.

curl https://api.supromail.com/v1/email/messages \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome aboard",
    "text": "Thanks for signing up!",
    "html": "<p>Thanks for signing up!</p>",
    "idempotency_key": "welcome-2026-07-26"
  }'

• Provide text, html, or both — at least one is required.
• from must use a verified domain, or you get 403 domain_not_verified.
• idempotency_key is optional but recommended. Reusing a key for the same message returns the original queued message; reusing it for a different message returns 409 idempotency_conflict.
• Sends count against the account's applicable quota. A limited send returns 429 quota_exceeded with Retry-After; where a daily quota applies, successful sends include X-Quota-Remaining.

Watch what you have sent in Email → Sending, and the per-event history in Email → Event log.

Send through SMTP

Use authenticated SMTP when your application or mail client already speaks SMTP. SMTP submissions use the same delivery pipeline and email allowance as API sends.

1. Enable the Email arm and verify the domain that will appear in the message's From header.
2. In Email → SMTP, switch to the verified domain, choose a username localpart such as postmaster, and create the credential.Admin Its username is [email protected].
3. Copy the generated password while it is shown. Supromail displays it once, so store it in your server-side secret manager before dismissing it.
4. Configure your client with the settings below and send a test message.

Use a From address on the credential's verified domain, then follow the test in Email → Sending and Email → Event log.

The suppression list

The suppression list is your workspace's do-not-email list. If an address is on it, Supromail will not send to it. Addresses land there two ways:

• Automatically, when a message hard-bounces or the recipient marks it as spam.
• Manually, when you add one yourself.Admin

You can also remove an addressAdmin if it was suppressed by mistake. When your relay reports a hard bounce or spam complaint, Supromail suppresses the recipient, records an email.bounced or email.complained event, and notifies any subscribed webhooks.

Receiving email

Supromail can receive mail on any verified domain. Business Email mailboxes receive and store their own addresses automatically; configure additional forwarding and webhook routes per domain in Email → Receiving.Admin

1. Point the domain's MX record at Supromail. The exact host and value are listed with the domain's other DNS records on the Domains page. Mail sent to a domain without the MX record never reaches Supromail.
2. Choose a receiving mode. Catch all receives mail sent to any address on the domain; catch some receives only the exact addresses you list.
3. Add destinations — email addresses for forwarding and/or HTTPS webhook URLs, comma-separated. Each received message is routed to every destination.

Webhook destinations receive an email.received POST with the parsed message: from, to, subject, text and HTML bodies, headers, decoded attachments, and inbound authentication results (spf, dkim, dmarc). It is signed exactly like other webhooks — X-Signature: sha256=… over "<timestamp>.<body>" — but with a per-domain signing secret shown on the Receiving page, not the per-webhook whsec_ secret.

Business Email

A professional inbox on your own domain, for addresses a person should read and reply to in a browser.

Mail sent to a Business Email address is stored and shown in the hosted webmail client. Paid Messaging plans include five accounts; the separate Business Email Free tier includes one mailbox per account.

1. In Email → Business Email, add an address on a verified domain, for example [email protected].Admin Supromail shows a password once — the same password signs in to webmail and authorises sending.
2. Creating the account is enough to send and receive at that address. Use Email → Receiving separately for catch-all or catch-some forwarding and webhook routes.
3. Sign in at webmail with the full address and password. Replies are sent through your verified domain and DKIM-signed, exactly like the API.

The username is always the full email address.

SMS

The SMS arm sends through Android phones you control, not a third-party gateway. Pair a phone, and Supromail routes each message to the right device, which sends it over its own SIM.

Pair a phone

Pairing connects a device to your workspace. The phone's permanent credential is never shown on screen — you scan a short-lived QR code instead.

1. In SMS → Devices, register a device with a name, and optionally its number, country, carrier, and limits.Admin
2. Choose Pair. The dashboard shows a QR code valid for 10 minutes.
3. Open the Supromail companion app on the phone and scan it. The app exchanges the code for a private device token and is now paired.

Managing devicesAdmin: Suspend instantly disables a phone and re-routes in-flight messages; Resume re-enables it; Rotate token issues a fresh credential, after which the phone must re-pair; Delete removes it, re-routing any in-flight messages first.

Send an SMS

curl https://api.supromail.com/v1/sms/messages \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "body": "Your code is 123456"
  }'

• to must be a full international number in E.164 format — a +, country code, then the number. National numbers are rejected.
• body is the message text; message is accepted as an alias.
• Optional: idempotency_key for safe retries, and routing_mode to override routing for a single message.

You can also send without code from the dashboard: Test (specific device) sends through one phone you pick, and Test route sends through your configured routing rules. Both send a real SMS.

Routing: choosing which phone sends

With more than one phone, the routing engine decides which handles each message. By default (auto) it balances across your online phones, preferring higher-priority ones. Routing rules go further, mapping recipients to a set of phones by prefix, country, or carrier. Each rule has a priority — higher wins — its phones, and a strategy:

Failover: if a chosen phone goes offline before accepting the assignment, or reports a definite failure, Supromail re-routes the message to a different phone. A phone is skipped after roughly 90 seconds of silence, and an unacknowledged assignment re-routes after about 2 minutes. Once Android has accepted the send, an ambiguous result becomes unknown rather than being retried.

Status, history, and control

SMS → Messages lists everything you have sent, newest first, with the masked recipient, status, sending phone, and timestamps. Open a message for its History (the full failover trail), Cancel (only while still queued), or Send now (force an immediate retry).

WhatsAppEarly access

The WhatsApp arm sends through your own WhatsApp numbers. You link a phone by scanning a QR code, exactly like WhatsApp Web, and Supromail sends as that number using an implementation of WhatsApp's companion-device protocol.

Link an account

1. In WhatsApp → Settings, enable the arm.Admin
2. In WhatsApp → Accounts, add the phone number.Admin A QR code appears and refreshes roughly every 20 seconds.
3. On the phone that owns the number, open WhatsApp → Settings → Linked devices → Link a device and scan the code. The account flips to connected. Keep the phone online.

Send a message

Use the linked account id, copyable on the Accounts page, with a key holding the whatsapp:send scope.

curl https://api.supromail.com/v1/whatsapp/messages \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "wa_account_id": "3f6c…",
    "to": "+2348012345678",
    "body": "Your order has shipped!"
  }'

Sending requires the linked account to be connected, otherwise you get 409 not_connected. Statuses advance queued → pending → sent → delivered → read as receipts arrive. If the connection may have transmitted a message but loses the result, the message becomes terminal unknown and is not retried automatically. Watch everything in WhatsApp → Messages and the event logs.

Telegram

The Telegram arm sends through your own bots using the official Bot API. Create a bot once, register its token, and send to any user, group, or channel that opted in.

Register a bot

1. In Telegram, message @BotFather, send /newbot, and follow the prompts to get a token like 123456:ABC-DEF….
2. In Telegram → Settings, enable the arm.Admin
3. In Telegram → Bots, paste the token and choose Register bot.Admin

The token is verified with Telegram, stored encrypted, and accepted exactly once — it is never shown again. If you lose it, BotFather can show it to you; Supromail cannot.

Send a message

curl https://api.supromail.com/v1/telegram/messages \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "tgbot_…",
    "chat_id": "-1001234567890",
    "text": "Deployment completed"
  }'

text is plain text up to 4,096 characters; body and message are accepted as aliases. Statuses run queued → pending → sent, where sent is final success — the Bot API has no delivered or read receipts. Transient errors that are safe to retry use bounded retries; permanent rejections such as tg_400 (chat not found) or tg_403 (bot blocked) mark the message failed. An ambiguous provider result becomes terminal unknown so a retry cannot duplicate the message.

Telegram has no status webhooks by design: the Bot API confirms acceptance only, so there is no later lifecycle event to subscribe to. Poll GET /v1/telegram/messages/{id} if your integration needs the outcome programmatically.

Members & roles

Invite teammates into your workspace and control what they can do. Roles are ranked owner > admin > member.

You can never grant a role higher than your own, nor remove or demote the last owner. In User management, invite by email and pick a role; Supromail gives you a shareable invite link to send yourself.

API keys & scopes

API keys let programs send through Supromail's API. Each key carries only the scopes you grant it, and can be restricted to source IP addresses.

In API Keys, create a key,Admin give it a name, choose its scopes, and optionally restrict it to specific source IP addresses or ranges. Choose test to mint an sk_test_ key instead of a live sk_live_ one.

A key can only do what its scopes allow and what the workspace's enabled arms allow:

Send the key as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Never place a live key in browser code, a mobile app, or a client-side repository. If a key might be exposed, revoke it and create a replacement.

Webhooks

Webhooks push real-time notifications from Supromail to your own URL when events happen. Each arm has its own webhooks.

When you create a webhook,Admin your URL must be HTTPS in production. Supromail shows a signing secret (whsec_…) exactly once — copy it to verify incoming calls. You can rotate it later.

Content-Type: application/json
User-Agent: Supromail-Webhooks/1
X-Supromail-Event: sms.delivered
X-Supromail-Timestamp: 1700000000
X-Signature: sha256=<hex>

Verify every request

1. Read the raw request body bytes before parsing JSON.
2. Reject the request if X-Supromail-Timestamp is not recent — older than five minutes, say — to block replays.
3. Build the signed string "<timestamp>.<raw-body>", compute HMAC-SHA256 with your whsec_ secret, and hex-encode it.
4. Compare it in constant time against each sha256=<hex> in X-Signature. If any matches, the request is valid.

import crypto from "node:crypto";

const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.SUPROMAIL_WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  throw new Error("invalid signature");
}

import hmac, hashlib, os

expected = "sha256=" + hmac.new(
    os.environ["SUPROMAIL_WEBHOOK_SECRET"].encode(),
    f"{timestamp}.{raw_body}".encode(),
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(signature, expected):
    raise ValueError("invalid signature")

Inbound mail is the one exception to the secret model: email.received is signed with a per-domain secret shown on the Receiving page. See Receiving email.

Account & activity

Manage your profile, audit what happened in the workspace, and delete your account.

Profile

Change your display name in Manage account. Your email address is managed by login and is not editable there.

Workspace name

Owners can rename the workspace in Manage account.

Activity (audit log)

Admins and owners can open Activity for an audit trail of meaningful actions — members invited, joined, or removed; roles changed; keys created or revoked; arms toggled; manual suppression edits; security alerts. High-volume per-message delivery events live in the Email and SMS event logs instead.

Delete your account

In the Danger zone of Manage account, permanently delete your own account. This is irreversible and asks you to type your workspace name to confirm.

Audit events are kept for at least 90 days regardless of plan; delivery events age out on your plan's window. See Limits & retention.

API reference

All API calls go to https://api.supromail.com. Authentication is a Bearer token in the Authorization header. This reference covers the machine API under /v1/….

All send endpoints are transactional: a 202 always means the message is safely queued. Email and SMS do not have per-message status endpoints; use their dashboard history and webhooks to observe outcomes. WhatsApp states are queued, pending, sent, delivered, read, failed, or unknown. Telegram states are queued, pending, sent, failed, or unknown, where sent is terminal. SMS states are listed under SMS.

Errors & retries

Every error returns the same JSON shape with an appropriate HTTP status:

{ "error": { "code": "domain_not_verified", "message": "..." } }

Always include a stable idempotency_key when retrying a send after a timeout or network failure. Where a daily quota applies, Supromail returns X-Quota-Remaining on successful sends.

Limits & retention

Plan allowances bound your email volume; the safety ceilings below exist to contain abuse from a leaked key, not to throttle normal use. All limits are configurable by your operator.

Plan allowances

Supromail does not charge usage overages. Email sends beyond the monthly allowance are rejected until the next calendar month or a plan change; creating a project or other resource above a plan cap is rejected until you reduce active resources or change plans. See Pricing for the per-plan numbers.

SMS safety ceilings

Request rate limits

A limited request returns 429 with Retry-After. WhatsApp throughput is additionally bounded by the linked phone and WhatsApp's own anti-abuse systems; Telegram by its flood control, roughly 30 messages/second per bot. Ramp fresh numbers gently.

Data retention

Plans & billing

Messaging and Business Email are independently billed monthly products that can be used separately or together. A paid Messaging plan includes five Business Email mailboxes; a Business Email subscription's allowance stacks on top of those. Paid plans are billed monthly in advance and renew automatically until cancelled.

A workspace owner manages each product in Plan & billing. An upgrade requires payment confirmation. A downgrade applies the lower tier while preserving the current paid period. A cancellation stops renewal at the end of that period; if Resume subscription is offered before the period ends, the owner can undo the pending cancellation without a new checkout. Once it ends, subscribing again requires checkout.

Existing resources are not silently deleted on downgrade, but you cannot create additional resources above the new plan's limit. See Pricing and the Terms.

Security & privacy

Supromail uses measures designed to protect the hosted Service and customer data, including access controls, protections for sensitive credentials, controls for connected sending resources, safeguards against abuse, and backup and recovery processes. No security measure eliminates all risk.

Read the Security page for reporting contacts and the Privacy Policy for data roles, retention, subprocessors, and international transfers. Do not use the Service for highly sensitive or regulated data unless we have agreed in writing that the intended use is supported.

Help & support

Every plan can start a support conversation through the chat widget in the Supromail app, and email [email protected]. Response targets vary by plan and are not service-level commitments. Enterprise support, including any dedicated chat, phone, or SLA, requires a separate written agreement.

For billing, security, abuse, or sales enquiries: [email protected], [email protected], [email protected], or [email protected].