qwicmail
Why qwicmail Pricing Docs About Legal
Sign in Request access →
Quickstart

Send your first email.

Roughly ten minutes from "approved tenant" to a delivered receipt. This guide assumes your access request has been approved and you can sign in at app.qwicmail.com.

Not approved yet? qwicmail uses closed onboarding — every tenant is manually verified before sending is enabled. If you haven't submitted a request, start at /request. Approval usually lands within one business day.

1. Mint an API key

In the customer portal, open Settings → API keys → New key. Give the key a name (we recommend the environment it's for — production, staging) and grant the emails:send scope. Two other scopes exist (domains:write, webhooks:write) which you only need if you intend to drive the corresponding resources from your code rather than from the portal.

The plaintext key (format qm_live_…) is shown exactly once. Copy it into your secret manager before closing the dialog — there is no way to recover it afterwards. If lost, revoke it and mint a fresh one.

2. Add and verify a sending domain

You can only send mail from a domain that's been verified for your tenant. The simplest path is the portal:

  1. Open Sending → Domains → Add domain.
  2. Enter the domain (e.g. mail.example.com).
  3. Publish the three DNS records the portal prints — one DKIM (required), one SPF (recommended), one DMARC (recommended in monitoring mode).
  4. Click Verify. Verification queries your authoritative nameservers directly and either marks the domain verified or returns the specific failure reason.

The same flow is available over the API — see the domains reference. Whichever path you use, DKIM is the only record verification depends on; SPF and DMARC are advisory but strongly recommended (and required by Gmail / Yahoo bulk sender rules above 5,000 messages/day).

3. Send

Once the domain is verified, every API key with emails:send can submit mail from any address on it. The minimum request: 

curl https://api.qwicmail.com/emails \
  -H "Authorization: Bearer $QWICMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    "alerts@mail.example.com",
    "to":      "customer@example.org",
    "subject": "Your receipt",
    "html":    "<p>Thanks for your order.</p>"
  }'

A successful submission returns 202 Accepted with the IDs the platform assigned:

{
  "id": "1f0c2c1a-…",                       // submission id (one per API call)
  "message_ids": ["8a3f1f5b-…"],            // one per accepted recipient
  "rejected": []                            // any recipients on the suppression list
}

Each message_id traces the email end-to-end. The same value is set as the SMTP Message-ID header on the outgoing wire, and appears in every webhook event the message produces. If you ever need to ask support about a single message, that's the value to quote.

What if a recipient is on the suppression list?

Recipients on your tenant suppression list (or the platform-global hard-bounce list) never reach the queue. They show up in the rejected array with a reason such as hard_bounce or complaint — the rest of the recipients in the call are accepted normally. If every recipient is suppressed, the response is 422 Unprocessable Entity with error: "all_recipients_suppressed".

4. (Optional) Listen for delivery events

Once your sending is in production, register an endpoint to receive delivery, bounce, complaint, and open events as HTTP POSTs: 

curl https://api.qwicmail.com/webhooks \
  -H "Authorization: Bearer $QWICMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":         "https://example.com/hooks/qwicmail",
    "description": "production event sink"
  }'

The response includes a one-time secret used to verify the HMAC signature on every event. Store it in your secret manager. See Webhook payloads for the event catalogue and the verification recipe.

5. Go live

Two things to know before you switch production traffic to qwicmail:

  • Tier escalation is automatic. New tenants start with a conservative 24-hour sending cap. The cap relaxes on day 14 and is removed entirely on day 30, provided your bounce and complaint rates stay clean. No paperwork — just send sensibly.
  • Auto-throttle protects everyone. If 24-hour bounce or complaint rates cross our thresholds, the platform throttles your tenant and surfaces the reason in the portal. Throttle lifts automatically after 7 days of clean sending.

For the practical deliverability checklist (DNS, warm-up posture, list hygiene) see Deliverability.