Create Email Domain

Beta

POST/v1/messaging/email-domains

Idempotent with Idempotency-Key header. Learn more

Registers a domain you own with the email bridge and returns the DKIM tokens to publish.

The domain starts in pending. Publish each returned token as a CNAME record in the domain's DNS, then call the verify action to move it to verified; only then can inboxes be created on it.

A domain can only be registered once across the platform, so registering one that is already in use returns a conflict error.

Permissions requiredValues:messaging:create

The role behind your API key or agent must grant every one of these permissions.

domainstring

The fully-qualified domain name to register (e.g. support.acme.com).

Supply a bare domain, not an email address; the value is lowercased before it is stored.

idstring

Email domain ID.

objectstringenumValues:email_domain

Resource type identifier.

domainstring

The fully-qualified domain name (e.g. support.acme.com).

statusstringenumValues:pendingverifiedfailed

Verification status.

pending: registered and awaiting DKIM confirmation.
verified: DKIM confirmed; the domain can send mail.
failed: verification could not be completed.

Inboxes can only be created on a verified domain.

dkim_tokensarray of string

The DKIM tokens that must be published in your DNS before the domain can be verified.

Publish each token as a CNAME record on the domain, then call the verify action to confirm them.

verified_atstring (date-time)nullable

When the domain's DKIM verification was confirmed.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

201

Successful response for Create Email Domain

Create Email Domain

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const emailDomain = await client.messaging.emailDomains.create({ domain: 'support.acme.com' });

console.log(emailDomain.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const emailDomain = await client.messaging.emailDomains.create({ domain: 'support.acme.com' });

console.log(emailDomain.id);

201 example

{
  "id": "emdom_2rk3omr8vshb",
  "object": "email_domain",
  "domain": "support.acme.com",
  "status": "pending",
  "dkim_tokens": [
    "abc123._domainkey.support.acme.com",
    "def456._domainkey.support.acme.com"
  ],
  "verified_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "emdom_2rk3omr8vshb",
  "object": "email_domain",
  "domain": "support.acme.com",
  "status": "pending",
  "dkim_tokens": [
    "abc123._domainkey.support.acme.com",
    "def456._domainkey.support.acme.com"
  ],
  "verified_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Create Email Domain

Authorization

Request Body

Returns

Responses