curl -X PATCH https://tawked.com/v1/email/domains/acme.sa \
-H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links"
}
}'const res = await fetch("https://tawked.com/v1/email/domains/acme.sa", {
method: "PATCH",
headers: {
Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links"
}
}),
});
const data = await res.json();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tawked.com/v1/email/domains/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'from_name' => '<string>',
'from_local' => '<string>',
'tracking' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
res = requests.patch(
"https://tawked.com/v1/email/domains/acme.sa",
headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"},
json={
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": True,
"clicks": False,
"subdomain": "links"
}
},
)
data = res.json(){
"id": "0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d",
"name": "acme.sa",
"state": "verified",
"created_at": "2026-10-23T09:00:00+00:00",
"verified_at": "2026-10-23T09:12:00+00:00",
"pending_until": null,
"records": [
{
"purpose": "dkim",
"type": "TXT",
"name": "tawked._domainkey.acme.sa",
"value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
"state": "found"
},
{
"purpose": "return_path",
"type": "MX",
"name": "send.acme.sa",
"value": "feedback-smtp.eu-west-1.amazonses.com",
"priority": 10,
"state": "found"
},
{
"purpose": "return_path",
"type": "TXT",
"name": "send.acme.sa",
"value": "v=spf1 include:_spf.tawked.com ~all",
"state": "found"
},
{
"purpose": "tracking",
"type": "CNAME",
"name": "links.acme.sa",
"value": "track.tawked.com",
"state": "found"
}
],
"defaults": {
"from_name": "متجر أكمي",
"from_local": "orders"
},
"authentication": {
"dkim": "pass",
"return_path": "working",
"dmarc": "none"
},
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links.acme.sa",
"state": "awaiting_dns",
"problem": "cname_missing",
"checked_at": "2026-10-23T10:00:00+00:00"
},
"receiving": null
}Update a domain
Changes a verified domain’s defaults (the sender’s name and the address’s local part a send uses when it names none), and switches its open and click tracking on its own subdomain. Every field is optional. Tracking needs one CNAME record at your DNS host (links.<domain> to track.tawked.com); the domain’s tracking.state moves from awaiting_dns to awaiting_tls to active. A live key of the application with the explicit email:manage: a full-access key does not hold it.
curl -X PATCH https://tawked.com/v1/email/domains/acme.sa \
-H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links"
}
}'const res = await fetch("https://tawked.com/v1/email/domains/acme.sa", {
method: "PATCH",
headers: {
Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links"
}
}),
});
const data = await res.json();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tawked.com/v1/email/domains/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'from_name' => '<string>',
'from_local' => '<string>',
'tracking' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
res = requests.patch(
"https://tawked.com/v1/email/domains/acme.sa",
headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"},
json={
"from_name": "متجر أكمي",
"from_local": "orders",
"tracking": {
"opens": True,
"clicks": False,
"subdomain": "links"
}
},
)
data = res.json(){
"id": "0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d",
"name": "acme.sa",
"state": "verified",
"created_at": "2026-10-23T09:00:00+00:00",
"verified_at": "2026-10-23T09:12:00+00:00",
"pending_until": null,
"records": [
{
"purpose": "dkim",
"type": "TXT",
"name": "tawked._domainkey.acme.sa",
"value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
"state": "found"
},
{
"purpose": "return_path",
"type": "MX",
"name": "send.acme.sa",
"value": "feedback-smtp.eu-west-1.amazonses.com",
"priority": 10,
"state": "found"
},
{
"purpose": "return_path",
"type": "TXT",
"name": "send.acme.sa",
"value": "v=spf1 include:_spf.tawked.com ~all",
"state": "found"
},
{
"purpose": "tracking",
"type": "CNAME",
"name": "links.acme.sa",
"value": "track.tawked.com",
"state": "found"
}
],
"defaults": {
"from_name": "متجر أكمي",
"from_local": "orders"
},
"authentication": {
"dkim": "pass",
"return_path": "working",
"dmarc": "none"
},
"tracking": {
"opens": true,
"clicks": false,
"subdomain": "links.acme.sa",
"state": "awaiting_dns",
"problem": "cname_missing",
"checked_at": "2026-10-23T10:00:00+00:00"
},
"receiving": null
}Authorizations
Authorization: Bearer . An application key (tk_live_, tk_test_) has full access, which covers every product and any product added later, or custom access, chosen when the key is created: one or more of the scopes verify:check, verify:send (includes verify:check), notifications:read, notifications:send (includes notifications:read), email:read, email:send (includes email:read), email:manage (includes email:send), webhooks:manage, email:inbound, notifications:templates (includes notifications:read), chat:menus, chat:attendant. No key made on the API keys page holds notifications:templates, full access included: the three template writes answer such a key 403 insufficient_scope. A connected app's key holds it. Nor chat:menus: the five conversation menu operations answer such a key 403 insufficient_scope, and a connected app's key holds it once the client approved it. Nor chat:attendant: the five auto-attendant operations answer such a key 403 insufficient_scope too, and a connected app's key holds it once the client approved it. email:manage and webhooks:manage are held only by a key someone chose them for: a full-access key, old or new, never holds them. email:inbound, which reads, deletes and forwards received e-mail, is opt-in on every key, full access included: a key holds it only when it was turned on when the key was created. A call outside the key's access answers 403 insufficient_scope and names the scope it needs in the WWW-Authenticate response header. A partner key (tk_partner_) always has full access. Whatever its access, a key is a server-side secret.
Headers
Up to 128 characters. A retry with the same key and the same body within 24 hours answers what the first call answered and changes nothing again; the same key with another body answers 409 idempotency_key_reused.
Path Parameters
The domain's id (a uuid) or its name (acme.sa).
Body
The sender's name shown to recipients, up to 120 characters; empty to clear.
The part of the address before the @: orders sends as orders@acme.sa.
{"opens": bool, "clicks": bool, "subdomain": "links"}: each key optional. Both off switches tracking off; links already sent keep working.
Response
Updated