Sign in

Replace the email domain

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Moves the app's email sending to a different domain it already owns.

The current domain is left in place until the new one verifies, so a domain that was already sending keeps sending while DNS propagates. That only holds if it was sending: replacing a domain whose own setup never finished leaves you with no working sender until the new one verifies. During the changeover List email domains returns both.

The new domain has the same requirements as Enable email sending for a domain: connected, ready, and different from the current one. Sending the domain already in use is a 400.

This works only when exactly one email domain is set up. If a previous replacement is still in flight you get a 400, so let it finish or remove one first.

This endpoint is limited to 10 requests per minute.

<Note>configuration_status moves through pending_dns_configuration, pending_user_dns_configuration, pending_domain_verification and then active. The three failed_ values mean setup stopped and you can retry with Retry email domain setup. Only active sends mail.</Note>

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

post/api/apps/{app_id}/custom-email-domains/replace

Path parameters

app_idstring required

ID of the app whose email domains you want to work with.

ID of the app whose email domains you want to work with.

Request body

domainstring required

Domain to move to. It has to be connected to this app and different from the current one.

sender_namestring required

Name recipients see in the From line.

from_emailstring email required

Address mail is sent from once the new domain verifies.

Example request

{
  "domain": "mail.example.com",
  "sender_name": "Nordwind Furniture",
  "from_email": "no-reply@mail.example.com"
}

Response

The new domain's setup started. The old one keeps sending until it verifies.

domainstring required

The domain being moved to.

statusstring required

Where the new domain's setup got to. The old one keeps sending until this reads active.

email_domain_idstring required

ID of this app's email configuration. It identifies the configuration, not the individual domain.

externalboolean

true when you brought the new domain yourself, false when it was bought through Base44.

Example response

{
  "domain": "mail.example.com",
  "status": "pending_domain_verification",
  "email_domain_id": "68b1c0d4e7b91d003c45a1f2",
  "dns_records": [
    {
      "name": "em1234.mail.example.com",
      "status": "pending",
      "ttl": 300,
      "type": "CNAME",
      "value": "u1234567.wl123.sendgrid.net"
    }
  ]
}

Changes