Email quickstart

At the end of this page your domain has sent an e-mail through the API, and your server hears what happened to it.

Ask your coding assistant to add Tawked Email to your project.

Before you start

A Tawked account with an application that has Email on. Sign up if you have none.
Early access to Tawked Email. It is early access: open the application’s Email area in the console and apply with what you send, how much a month and your domain. Tawked’s team reviews each request and tells you on WhatsApp, in the console and by e-mail. Until it is approved, you cannot add a domain, and a send answers 403 email_early_access.
A domain you own, and access to its DNS.

Verify your domain

Open the application, then Email → Setup, and add your domain, acme.sa for example. The console shows three CNAME records:

Type	Name	Value
CNAME	`<token1>._domainkey.acme.sa`	`<token1>.dkim.amazonses.com`
CNAME	`<token2>._domainkey.acme.sa`	`<token2>.dkim.amazonses.com`
CNAME	`<token3>._domainkey.acme.sa`	`<token3>.dkim.amazonses.com`

Add the three at your DNS provider exactly as shown. They sign every message with DKIM, which is what mail servers check. Tawked looks for them every ten minutes; press Check now to look at once. Most providers publish a record within minutes. A domain whose records are not found within 72 hours is marked failed, and you can add it again.Nothing else in your DNS changes: your MX records, your SPF record and your mailboxes stay as they are.

If your domain has no DMARC record yet, add one: a TXT record at _dmarc.acme.sa with v=DMARC1; p=none; rua=mailto:dmarc@acme.sa to start. Gmail and Yahoo expect DMARC from domains that send at volume, and DKIM from these records is what makes your mail pass it.

Create a live key

On Application settings → API keys, press Create a key. Choose the type Live, and under Access either All products or Custom with Email set to Send (the email:send scope). Copy the key: it shows once. Put it in your server’s environment as TAWKED_KEY.A test key does not work here: the e-mail endpoints answer it 403 live_key_required. Send your first messages to your own address instead.

Send a message

curl -X POST https://tawked.com/v1/email/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "from": { "name": "متجر أكمي", "address": "orders@acme.sa" },
    "to": "you@example.com",
    "subject": "طلبك رقم 1042 قيد التجهيز",
    "html": "<p>مرحبًا سارة،</p><p>استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.</p>",
    "text": "مرحبًا سارة، استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.",
    "reference": "order-1042"
  }'

const res = await fetch('https://tawked.com/v1/email/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-confirmation',
  },
  body: JSON.stringify({
    from: { name: 'متجر أكمي', address: 'orders@acme.sa' },
    to: 'you@example.com',
    subject: 'طلبك رقم 1042 قيد التجهيز',
    html: '<p>مرحبًا سارة،</p><p>استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.</p>',
    text: 'مرحبًا سارة، استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.',
    reference: 'order-1042',
  }),
});
const message = await res.json(); // keep message.id next to the order

$res = Http::withToken(env('TAWKED_KEY'))
    ->withHeaders(['Idempotency-Key' => 'order-1042-confirmation'])
    ->post('https://tawked.com/v1/email/messages', [
        'from' => ['name' => 'متجر أكمي', 'address' => 'orders@acme.sa'],
        'to' => 'you@example.com',
        'subject' => 'طلبك رقم 1042 قيد التجهيز',
        'html' => '<p>مرحبًا سارة،</p><p>استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.</p>',
        'text' => 'مرحبًا سارة، استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.',
        'reference' => 'order-1042',
    ]);
$id = $res->json('id'); // keep the id next to the order

import os, requests

res = requests.post(
    "https://tawked.com/v1/email/messages",
    headers={
        "Authorization": f"Bearer {os.environ['TAWKED_KEY']}",
        "Idempotency-Key": "order-1042-confirmation",
    },
    json={
        "from": {"name": "متجر أكمي", "address": "orders@acme.sa"},
        "to": "you@example.com",
        "subject": "طلبك رقم 1042 قيد التجهيز",
        "html": "<p>مرحبًا سارة،</p><p>استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.</p>",
        "text": "مرحبًا سارة، استلمنا طلبك رقم 1042 وهو قيد التجهيز الآن.",
        "reference": "order-1042",
    },
)
message_id = res.json()["id"]  # keep the id next to the order

The answer is 202 Accepted: the message is recorded and on its way.

{
  "id": "3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40",
  "status": "accepted",
  "from": { "name": "متجر أكمي", "address": "orders@acme.sa" },
  "to": "you@example.com",
  "subject": "طلبك رقم 1042 قيد التجهيز",
  "reference": "order-1042",
  "price_halalas": 1,
  "created_at": "2026-10-09T12:00:00+03:00"
}

The likely refusals: 403 insufficient_scope (the key’s access does not include Email send), 403 email_early_access (the account has not been granted early access yet), 409 no_verified_domain (no domain of this application is verified yet), 422 sender_not_verified (the from address is on another domain). Sending email lists every code.

Read the status

curl https://tawked.com/v1/email/messages/3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40 \
  -H "Authorization: Bearer $TAWKED_KEY"

status moves from accepted to sent and delivered as the receiving mailbox answers, or ends as bounced or failed with error set. The message is on Email → Messages too.

Add the webhook

On Application settings → Webhooks, set your endpoint’s URL. Every event of the application reaches it, so Tawked then posts email.delivered, email.bounced, email.complained and email.failed as they happen, signed like every other event. See Webhooks for the signature and Sending email for the payload.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Email quickstart