Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qflowhub.io/llms.txt

Use this file to discover all available pages before exploring further.

By default, emails sent through Qflow use shared sending infrastructure. If you want recipients to see emails coming from your own domain (e.g. mail.yourcompany.com), authenticate a domain at SendGrid via the API. Why bother: improved deliverability (your DKIM signature, your reputation), recipient trust (no via sendgrid.net annotation in Gmail), full From / Reply-To control.

​
Lifecycle

1

Create the domain

POST /api/comms/domain with your domain. SendGrid issues 3 CNAMEs.
2

Publish the CNAMEs at your registrar

Add the records exactly as returned. DNS changes can take minutes to hours to propagate.
3

Verify

POST /api/comms/domain/verify. SendGrid checks DNS; on success, sending from your domain is automatically activated.
After successful verify, every send from the calling user’s account routes through the custom domain — no per-template setting required.

​
Endpoints

MethodPathPurpose
POST/api/comms/domainCreate — body: {"domain": "mail.example.com"}
GET/api/comms/domainRead current state (id, domain, verified, enabled, DNS records)
POST/api/comms/domain/verifyValidate DNS at SendGrid; auto-activates on success
POST/api/comms/domain/activateRe-enable after a manual deactivate (no DNS recheck)
POST/api/comms/domain/deactivateDisable without losing setup (sends fall back to default sender)
POST/api/comms/domain/deleteRemove entirely (clears your domain id, deletes from SendGrid)

​
Create

curl -X POST 'https://api.qflowhub.io/comms/v1/api/comms/domain' \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"domain": "mail.yourcompany.com"}'
Response (200): 
{
  "id": 30751683,
  "domain": "mail.yourcompany.com",
  "verified": false,
  "enabled": false,
  "dnsRecords": [
    { "type": "cname", "host": "em2037.mail.yourcompany.com",       "data": "u44936656.wl157.sendgrid.net",            "valid": false },
    { "type": "cname", "host": "s1._domainkey.mail.yourcompany.com", "data": "s1.domainkey.u44936656.wl157.sendgrid.net", "valid": false },
    { "type": "cname", "host": "s2._domainkey.mail.yourcompany.com", "data": "s2.domainkey.u44936656.wl157.sendgrid.net", "valid": false }
  ]
}
Publish those three CNAMEs at your registrar, then call verify.

​
Verify

curl -X POST 'https://api.qflowhub.io/comms/v1/api/comms/domain/verify' \
  -H 'Authorization: Bearer <token>'
Success: 
{ "verified": true, "enabled": true, "reasons": [] }
Failure (DNS not propagated yet, or wrong record value): 
{
  "verified": false,
  "enabled": false,
  "reasons": [
    { "name": "mail_cname", "valid": false, "reason": "Expected CNAME for \"em2037.mail.yourcompany.com\" to match \"u44936656.wl157.sendgrid.net\"." },
    { "name": "dkim1",      "valid": false, "reason": "..." },
    { "name": "dkim2",      "valid": false, "reason": "..." }
  ]
}
DNS changes can take minutes to hours to propagate. Retry verify periodically.

​
Activate / Deactivate

/activate and /deactivate toggle the enabled flag without touching SendGrid records. Use /deactivate when you suspect DNS issues are hurting deliverability — your sends fall back to the default sender immediately, but the SendGrid record + DNS setup stay in place. Re-/verify (which auto-activates on success) or /activate (no DNS recheck) when you’re ready to resume.
/activate returns 409 domain_not_verified if the domain has never passed verification. First activation must follow a successful /verify.

​
Delete

POST /api/comms/domain/delete clears the domain id from your account and deletes the record at SendGrid. After delete, GET /api/comms/domain returns 404. You can recreate the same domain freshly afterwards.

​
One domain per account

You can have at most one custom domain per Qflow account at a time. If a domain is configured, POST /api/comms/domain returns 409 domain_already_configured — delete first if you want to switch.