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

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](/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): 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](/api-reference/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>

## 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. The old one keeps sending until this reads `active`.
  - `email_domain_id` string, required — ID of this app's email configuration. It identifies the configuration, not the individual domain.
  - `external` boolean — `true` when you brought the new domain yourself, `false` when it was bought through Base44.
  - `dns_records` EmailDnsRecordResponse[], nullable — Records to publish for the new domain.
    - `type` string, required — Record type: `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: `pending`, `verified` or `failed`. `null` before the first check.

## Other responses

- `400` — The new domain cannot 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 does not include custom domains.
- `403` — You don't have access to this app, the app does not exist, you used a workspace API key, or the domain is suspended.
- `404` — The new domain is not connected to this app, or the app has no email domain to replace.
- `412` — The new domain is not ready yet: it still needs verifying, or its DNS has not finished propagating.
- `422` — Validation Error
- `429` — Rate limit exceeded (10 requests per minute).

## Changes

- **2026-08-26** `f2727732ced1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/custom-email-domains/replace/post.md)

---

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