---
title: "Replace the email domain"
method: POST
path: "/api/apps/{app_id}/custom-email-domains/replace"
---

# Replace the email domain

`POST /api/apps/{app_id}/custom-email-domains/replace`

<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.

A current domain that is already sending keeps sending until the new one verifies, so mail keeps going out while DNS propagates. A current domain that never finished setup isn't sending, and nothing sends until the new domain verifies. During the changeover [List email domains](/api-reference/list-email-domains) returns both.

The new domain has the same requirements as [Enable email sending for a domain](/api-reference/enable-email-sending-for-a-domain). It has to be connected, ready, and different from the current one. Sending the domain already in use is rejected.

This works only when the app has exactly one email domain. A replacement that's still in flight leaves two, and this call is rejected until that clears. Base44 tries to remove the old domain once the new one verifies, but that doesn't happen on every path and can fail quietly. When a replacement is rejected, read [List email domains](/api-reference/list-email-domains) and clear the extra domain with [Disable email sending for a domain](/api-reference/disable-email-sending-for-a-domain).

## Path parameters

- `app_id` string, required — ID of the app whose email domains you want to work with.

## Request body

- ReplaceEmailDomainRequest — Request to replace email domain with a new one.
  - `domain` string, required — Domain to move to. It has to be connected to this app and different from the current one.
  - `sender_name` string, required — Name recipients see in the From line.
  - `from_email` string, email, required — Address mail is sent from once the new domain verifies.

## Response `200`

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

- ReplaceEmailDomainResponse — Response for replacing email domain.
  - `domain` string, required — The domain being moved to.
  - `status` string, required — Where the new domain's setup got to. Only `active` sends mail, and the old domain keeps sending until this reads it. The `pending_` values mean setup is still in progress, and the `failed_` values mean it stopped and you can start it again with [Retry email domain setup](/api-reference/retry-email-domain-setup).
  - `email_domain_id` string, required — ID of this app's email configuration. It identifies the configuration, not the individual domain.
  - `external` boolean — Whether you brought the new domain yourself (`true`) or bought it through Base44 (`false`).
  - `dns_records` EmailDnsRecordResponse[], nullable — Records to publish for the new domain.
    - `type` string, required — Record type. Either `CNAME`, `TXT` or `MX`.
    - `name` string, required — Host the record goes on.
    - `value` string, required — Value to publish.
    - `ttl` integer — Time to live to publish the record with, in seconds.
    - `status` string, nullable — Whether Base44 can see the record yet. Either `pending`, `verified` or `failed`. The value is `null` before the first check.

## Other responses

- `400` — The new domain can't send mail, is the one already in use, or the app has more than one email domain.
- `401` — Missing or invalid credentials.
- `402` — This workspace's plan doesn't include custom domains.
- `403` — You don't have access to this app, you used a workspace API key, or the email domain is suspended. A suspended domain says why in the message.
- `404` — The new domain isn't connected to this app, the app has no email domain to replace, or the app doesn't exist.
- `412` — The domain isn't ready yet. It still needs verifying, or its DNS hasn't finished propagating.
- `422` — The request body is missing a required field or has an invalid value.
- `429` — Rate limit exceeded. The base limit is 10 requests per minute. See [Rate limits](/developers/references/app-management/get-started/rate-limits) for the multiplier your plan gets.

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/adexad/base44-app-management-api/revisions/6ad855bf424f/schema)