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.

Permission requiredValues:messaging:create

The role behind your API key or agent must grant this permission.

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.

mail_from_domainstringnullable

The subdomain used as the envelope return path for mail sent from this domain.

Publishing the two records below makes the return path match the sender address. Until you do, mail clients show your mail as coming from your address "via amazonses.com".

mail_from_mx_recordstringnullable

The MX record to publish on mail_from_domain, for delivery of bounces and complaints.

mail_from_spf_recordstringnullable

The SPF record to publish as a TXT record on mail_from_domain.

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"
  ],
  "mail_from_domain": null,
  "mail_from_mx_record": null,
  "mail_from_spf_record": null,
  "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"
  ],
  "mail_from_domain": null,
  "mail_from_mx_record": null,
  "mail_from_spf_record": null,
  "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