Email: domains, DNS & sending

Before WeZend sends email in your name, you prove that you own the domain. This is what keeps your mail out of the spam folder — inbox providers trust mail that is cryptographically tied to a verified domain.

1. Add your domain

In the dashboard, open Settings → Email domains and add the domain you send from (for example mail.yourcompany.com). The API equivalent:

curl -X POST https://api.wezend.com/v1/account/email-domains \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.yourcompany.com" }'

The response lists the exact DNS records to create: an SPF record (which servers may send for you), a DKIM key (a signature receivers verify) and a DMARC policy (what receivers should do when a message fails the first two).

2. Create the DNS records

Copy each record into your DNS provider exactly as shown. DNS changes can take from minutes to a few hours to propagate.

3. Verify

Click Verify in the dashboard or call POST /v1/account/email-domains/:id/verify — the platform runs live DNS lookups for all three records, persists the result and returns it:

{
  "spf_verified": true,
  "dkim_verified": false,
  "dmarc_verified": true,
  "status": "pending",
  "checks": {
    "spf":   { "ok": true,  "reason": "ok" },
    "dkim":  { "ok": false, "reason": "wrong_selector", "detail": "smtp", "selector": "zc1", "hint": "You published a valid DKIM key under the \"smtp\" selector — that's another provider's key (e.g. your mailbox host), not WeZend's. WeZend signs with the \"zc1\" selector, so add the \"zc1._domainkey\" CNAME shown above; the \"smtp\" one can stay, it's harmless." },
    "dmarc": { "ok": true,  "reason": "ok", "policy": "quarantine" }
  }
}

SPF and DKIM must both pass before status becomes verified; DMARC is recommended but not blocking.

checks carries one entry per record, so a failed check tells you what to fix instead of showing a bare red cross:

• ok — that record's boolean.
• reason — a stable machine code. Branch on this in your own tooling; the wording of hint is not part of the contract.
• hint — one line of human wording for whoever manages the DNS. null on a passing check, with one exception (see DMARC below).
• detail — the value the check turned on: the selector actually found, the SPF include that is missing, the host that holds no record. null when not applicable.
• selector — DKIM only: the selector WeZend signs with, so you can name it in your own interface. policy — DMARC only: the parsed p= value, one of none, quarantine or reject.

Re-running Verify is always safe. If you have seen a red DKIM cross on a record you know is published correctly, run it again — verification used to false-negative DKIM on every domain, because WeZend's managed key host is published as a TXT record while the health check only probed A and CNAME.

Reason codes

• ok — the record is present and correct.
• esp_target_unresolved — this one is on WeZend, not you. Our own SPF include or managed-DKIM key host isn't resolving, so no record you publish can pass yet. detail names the host. Don't send the domain owner into their DNS over this — contact support and quote the host.
• no_spf_record — the domain has no v=spf1 TXT record at all.
• missing_include — an SPF record exists but doesn't contain WeZend's include (detail). Add it to the record you already have; don't publish a second SPF record.
• not_published — DKIM: nothing at <selector>._domainkey.<domain>. detail is the host that was queried.
• wrong_cname_target — DKIM: a CNAME exists at the right host but points somewhere else. detail is the host it must point to.
• wrong_selector — DKIM: the domain does publish a valid DKIM key, but under a different selector. detail is the selector that was found.
• no_record — DMARC: no v=DMARC1 TXT record at _dmarc.<domain>.

The wrong-selector case

This is the failure real customers hit. The DNS looks right, SPF and DMARC pass, DKIM is red — and the cause is that the published key belongs to someone else. A mailbox host had already set up DKIM under its own selector, typically smtp._domainkey or default._domainkey, and that record was taken for the one WeZend asked for.

WeZend signs with its own selector (zc1 by default) and holds no other provider's private key, so a foreign selector can never count as a pass. Publish the <selector>._domainkey CNAME from step 2 as well. The other provider's record can stay — the two coexist, and removing it would break the mail you send through that provider.

DMARC enforcement while DKIM is failing

A DMARC check that passes still returns a hint when the policy is p=quarantine or p=reject and DKIM is failing. That combination is what actually puts your mail in the spam folder: you have told receivers to quarantine or reject anything that fails authentication, and DKIM is failing. Keep DMARC at p=none until DKIM verifies, then tighten it.

4. Send

Once verified, email is just another channel on the same endpoint you already use:

curl -X POST https://api.wezend.com/v1/messages/send \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "channel": "email",
    "sender": "hello@mail.yourcompany.com",
    "subject": "Welcome!",
    "html": "<h1>Hi there</h1><p>Thanks for signing up.</p>"
  }'

Opens and clicks are tracked automatically (a tracking pixel and rewritten links), bounces and complaints feed the suppression list, and your sender reputation is monitored continuously — see Deliverability.