Domains

Create Domain

POST /domains/

Register a new email domain.

Request Body

Field	Type	Required	Description
name	string	Yes	Domain name (e.g. mycompany.com). Auto-lowercased.
partner_ref	string	No	Master only. Attribute the domain to a tenant at creation time. Ignored when sent by a customer token (the caller’s own partner_ref always wins).

Master tokens: always send partner_ref

When the platform owner creates a domain on behalf of a tenant (the typical Odoo-orchestrated flow), pass partner_ref in the body. Otherwise the domain is recorded with no owner and the tenant’s domains_used quota counter is not incremented. Use PUT /domains/{name}/owner to fix attribution after the fact.

Example

# Customer token — the API uses your token's partner_ref
curl -X POST https://api.emboux.com/domains/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mycompany.com"}'

# Master token — attribute on creation
curl -X POST https://api.emboux.com/domains/ \
  -H "Authorization: Bearer MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "mycompany.com", "partner_ref": "partner_42"}'

Response 201 Created

{
  "id": 1,
  "name": "mycompany.com",
  "created_at": "2025-01-15T10:30:00"
}

Errors

Status	Detail
400	Domain already exists
403	Domain quota exceeded

---

List Domains

GET /domains/

Returns all domains visible to the authenticated key.

• Master token: returns all domains
• Client token: returns only domains belonging to that partner

Example

curl https://api.emboux.com/domains/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

[
  {
    "id": 2,
    "name": "example.org",
    "created_at": "2025-01-16T08:00:00"
  },
  {
    "id": 1,
    "name": "mycompany.com",
    "created_at": "2025-01-15T10:30:00"
  }
]

---

Delete Domain

DELETE /domains/{domain_name}

Permanently removes a domain and all its mailboxes and aliases (cascade delete).

Caution

This action is irreversible. All email data for this domain will be lost.

Path Parameters

Parameter	Type	Description
domain_name	string	The domain name to delete

Example

curl -X DELETE https://api.emboux.com/domains/mycompany.com \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204 No Content

No response body.

Errors

Status	Detail
404	Domain not found

Note

Deleting a subdomain also removes any provider-side configuration that was installed for it when it was registered. You do not need to revoke credentials or clean up DNS separately.

---

Register Subdomain

POST /domains/{domain_name}/register-subdomain

Complete provider-side setup for a subdomain whose parent is a verified wildcard domain. After a successful call the subdomain can send outbound mail using the parent’s DKIM identity.

Available to both master and customer tokens. Customer tokens may only register subdomains they own (filtered by partner_ref — a 404 is returned for any other domain).

When to call

Call this once, right after creating a subdomain under a verified wildcard parent. If you create domains via the Odoo module, this call is dispatched automatically and you do not need to invoke it yourself.

Path Parameters

Parameter	Type	Description
domain_name	string	Subdomain name (must have at least 3 parts, e.g. client1.example.com)

Example

curl -X POST https://api.emboux.com/domains/client1.example.com/register-subdomain \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "name": "client1.example.com",
  "verification_token": "",
  "dkim_tokens": [],
  "verified": true,
  "dns_records": [],
  "provider": "mailgun"
}

Errors

Status	Detail
400	Name is not a subdomain (≤ 2 parts)
404	Domain not found (or not owned by this customer token)

---

Wildcard / Parent Domain

PUT /domains/{domain_name}/parent

Set parent_domain and/or is_wildcard for a domain. Master token only.

Request Body

Field	Type	Required	Description
parent_domain	string	No	Name of the parent domain (or null to clear)
is_wildcard	boolean	No	Enable wildcard mode for this domain

Example

curl -X PUT https://api.emboux.com/domains/ganemo.com/parent \
  -H "Authorization: Bearer YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_wildcard": true}'

Response 200 OK

{
  "name": "ganemo.com",
  "parent_domain": null,
  "is_wildcard": true
}

Tip

When creating a subdomain (e.g. client1.ganemo.com), the API auto-detects the parent and links them automatically. See the Wildcard DNS guide for details.

---

DNS Check

GET /domains/{domain_name}/dns-check

Verify that DNS records are configured correctly for a domain.

Response 200 OK

{
  "name": "ganemo.com",
  "all_ok": true,
  "records": [
    {"record_type": "MX", "name": "ganemo.com", "expected": "mx1.emboux.com", "status": "ok"},
    {"record_type": "TXT", "name": "ganemo.com", "expected": "include:emboux.com", "status": "ok"}
  ]
}

Each record has a status of ok, missing, or incorrect.

DKIM and tracking records appear after /verify

The DKIM CNAMEs and the tracking CNAME (e.g. email.{domain}) are populated from the response of POST /domains/{name}/verify. Until that call has succeeded once, dns-check only reports MX and SPF. If you see all_ok: true with only those two records, run /verify first.

---

Transfer Domain Owner

PUT /domains/{domain_name}/owner

Reassign a domain to a different tenant. The endpoint atomically updates the domain’s partner_ref and adjusts the domains_used counter on both the previous and the new owner’s API keys.

Master token only.

Request Body

Field	Type	Required	Description
partner_ref	string | null	Yes	The new owner’s partner_ref. Pass null to unassign (orphan) the domain.

Behavior

• Reassign (partner_ref: "P_new") — the API validates that at least one active API key exists for P_new (refusing with 400 otherwise so domains can’t be silently orphaned into a non-existent tenant). The previous owner’s domains_used is decremented and the new owner’s is incremented.
• Unassign (partner_ref: null) — only the previous owner’s counter goes down; no new partner is credited.
• No-op (target equals current owner) — no counters move; the response echoes current state.

Example

curl -X PUT https://api.emboux.com/domains/client.example.com/owner \
  -H "Authorization: Bearer MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partner_ref": "partner_42"}'

Response 200 OK

{
  "name": "client.example.com",
  "partner_ref": "partner_42",
  "previous_partner_ref": "partner_17"
}

Errors

Status	Detail
400	No active api_key for partner_ref={value}
403	Master token required
404	Domain not found

When to use this

Use the transfer endpoint instead of DELETE + recreate when correcting domain attribution. DELETE cascades to all mailboxes and aliases — transfer keeps every dependent resource intact and only adjusts the partner pointer.

---

Activate / Suspend

PUT /domains/{name}/suspend and PUT /domains/{name}/activate toggle the suspended flag on a domain. Suspended domains reject inbound mail at Postfix/Dovecot.

curl -X PUT https://api.emboux.com/domains/client.example.com/activate \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "name": "client.example.com",
  "suspended": false,
  "message": "Domain activated"
}

Side effect: provider credential bootstrap

For Mailgun-backed domains, /activate will provision the per-tenant SMTP credential in Postfix’s sender-dependent SASL map if no credential is yet installed for the root domain. Without this, outbound from a freshly activated domain would be accepted by Postfix and bounce later at relay (5.7.1 Relaying denied) — invisible to the API caller.

The provisioning is idempotent and best-effort: a failure logs a warning but never breaks /activate. To force a rotation or to recover from a failed bootstrap, call POST /domains/{name}/provider-credential explicitly.

This applies to Mailgun only. SES uses a single account-wide credential and needs no per-domain SASL line.