Enable inbound on a domain

Turn inbound e-mail on or off for a domain you own with PUT /v3/domains/{name}/inbound and read back the MX record to publish.

Enabling inbound appends the MX requirement to the domain’s dns_records — {"type":"MX","host":"<domain>","value":"10 inbound.wemail.io","ok":false} — and fills the inbound block of the domain object: { "enabled": true, "mx": [{ "host": "inbound.wemail.io", "priority": 10 }], "ok": false, "existing_mx": [], "checked_at": null, "check_error": null }. existing_mx lists the MX records the domain already publishes (other than ours): when it is not empty the domain already receives mail elsewhere, and replacing those records moves ALL of its mail to wemail — receive on a dedicated subdomain such as in.example.com instead. Publish <domain>. MX 10 inbound.wemail.io, then call Verify a domain (or wait for the six-hourly re-check) to see inbound.ok become true — or POST /v3/domains/{name}/inbound/check for an MX-only re-check (12 per minute per key; inbound.checked_at is the time of the last completed lookup, and a DNS failure keeps the previous result with inbound.check_error: "dns_unavailable"). Disabling removes the MX entry and stops acceptance at the next SMTP transaction.

PUT /v3/domains/{name}/inbound

Request body

Parameter	Type	Required	Description
`enabled`	boolean	Required	`true` to start accepting mail for the domain (once it is verified), `false` to stop.

The toggle does not require the domain to be verified yet — you need the MX requirement before your DNS is complete — but mail is accepted only when the domain is `verified` and inbound is enabled. Only the workspace that owns the domain may toggle it (a domain shared from another workspace answers 403 forbidden), the plan must include inbound parsing (403 plan_not_allowed), and a domain name already receiving inbound mail in another workspace answers 409 inbound_domain_taken — one customer’s mail is never delivered to another. Requires a full_access key.

Responses

Status	Description
`200`	OK. The full domain object with its updated `inbound` block and `dns_records`.
`401`	Missing or invalid API key.
`403`	`forbidden` — the domain is shared from another workspace; `plan_not_allowed` — your plan does not include inbound e-mail.
`404`	No such domain on your account.
`409`	`inbound_domain_taken` — another workspace already receives inbound mail for this name.

Code examples

cURL

curl -X PUT https://api.wemail.io/v3/domains/leads.example.com/inbound \
  -H "Authorization: Bearer afn_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
# then publish:  leads.example.com.  MX  10 inbound.wemail.io

Node.js

const res = await fetch("https://api.wemail.io/v3/domains/leads.example.com/inbound", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WEMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ enabled: true }),
});
const domain = await res.json();
console.log(domain.inbound); // { enabled: true, mx: [{ host: "inbound.wemail.io", priority: 10 }], ok: false }

Python

import os, requests

r = requests.put(
    "https://api.wemail.io/v3/domains/leads.example.com/inbound",
    headers={"Authorization": f"Bearer {os.environ['WEMAIL_API_KEY']}"},
    json={"enabled": True},
)
domain = r.json()
print(domain["inbound"])  # publish the MX record, then verify the domain until inbound.ok is true

client, _ := wemail.NewClient(os.Getenv("WEMAIL_API_KEY"))
ctx := context.WithValue(context.Background(), wemail.ContextAccessToken, os.Getenv("WEMAIL_API_KEY"))
domain, _, err := client.API.DomainsAPI.SetDomainInbound(ctx, "leads.example.com").
    SetDomainInboundRequest(wemail.SetDomainInboundRequest{Enabled: true}).Execute()

ResponseExample response

{
  "id": "dom_01HCXV5Z…",
  "domain": "leads.example.com",
  "status": "verified",
  "spf": true,
  "dkim": true,
  "dmarc": true,
  "dkim_selector": "afn8kq2x1w9",
  "tracking_subdomain": "track.leads.example.com",
  "dns_records": [
    { "type": "CNAME", "host": "afn8kq2x1w9._domainkey.leads.example.com", "value": "afn8kq2x1w9.dkim.wemail.io", "ok": true },
    { "type": "TXT",   "host": "leads.example.com",                        "value": "v=spf1 include:wemail.io ~all", "ok": true },
    { "type": "CNAME", "host": "track.leads.example.com",                  "value": "track.wetik.io", "ok": true },
    { "type": "TXT",   "host": "_dmarc.leads.example.com",                 "value": "v=DMARC1; p=none;", "ok": true },
    { "type": "MX",    "host": "leads.example.com",                        "value": "10 inbound.wemail.io", "ok": false }
  ],
  "inbound": {
    "enabled": true,
    "mx": [{ "host": "inbound.wemail.io", "priority": 10 }],
    "ok": false,
    "existing_mx": [],
    "checked_at": "2026-08-16T10:02:41.000Z",
    "check_error": null
  },
  "created_at": "2026-08-16T09:30:00.000Z",
  "verified_at": "2026-08-16T10:02:41.000Z"
}