> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace the email domain
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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).
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/custom-email-domains/replace
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/custom-email-domains/replace:
post:
summary: Replace the email domain
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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).
operationId: replace_email_domain_api_apps__app_id__custom_email_domains_replace_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose email domains you want to work with.
title: App Id
description: ID of the app whose email domains you want to work with.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceEmailDomainRequest'
responses:
'200':
description: >-
The new domain's setup started. The old one keeps sending until it
verifies.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceEmailDomainResponse'
'400':
description: >-
The new domain can't send mail, is the one already in use, or the
app has more than one email domain.
'401':
description: Missing or invalid credentials.
'402':
description: This workspace's plan doesn't include custom domains.
'403':
description: >-
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':
description: >-
The new domain isn't connected to this app, the app has no email
domain to replace, or the app doesn't exist.
'412':
description: >-
The domain isn't ready yet. It still needs verifying, or its DNS
hasn't finished propagating.
'422':
description: >-
The request body is missing a required field or has an invalid
value.
'429':
description: >-
Rate limit exceeded. The base limit is 10 requests per minute. See
[Rate
limits](/developers/references/apps-api/get-started/rate-limits) for
the multiplier your plan gets.
components:
schemas:
ReplaceEmailDomainRequest:
properties:
domain:
type: string
title: Domain
description: >-
Domain to move to. It has to be connected to this app and different
from the current one.
example: mail.example.com
sender_name:
type: string
title: Sender Name
description: Name recipients see in the From line.
example: Nordwind Furniture
from_email:
type: string
format: email
title: From Email
description: Address mail is sent from once the new domain verifies.
example: no-reply@mail.example.com
type: object
required:
- domain
- sender_name
- from_email
title: ReplaceEmailDomainRequest
description: Request to replace email domain with a new one.
ReplaceEmailDomainResponse:
properties:
domain:
type: string
title: Domain
description: The domain being moved to.
example: mail.example.com
status:
type: string
title: Status
description: >-
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).
example: pending_domain_verification
email_domain_id:
type: string
title: Email Domain Id
description: >-
ID of this app's email configuration. It identifies the
configuration, not the individual domain.
example: 68b1c0d4e7b91d003c45a1f2
external:
type: boolean
title: External
description: >-
Whether you brought the new domain yourself (`true`) or bought it
through Base44 (`false`).
default: false
example: false
dns_records:
anyOf:
- items:
$ref: '#/components/schemas/EmailDnsRecordResponse'
type: array
- type: 'null'
title: Dns Records
description: Records to publish for the new domain.
example:
- name: em1234.mail.example.com
status: pending
ttl: 300
type: CNAME
value: u1234567.wl123.sendgrid.net
type: object
required:
- domain
- status
- email_domain_id
title: ReplaceEmailDomainResponse
description: Response for replacing email domain.
EmailDnsRecordResponse:
properties:
type:
type: string
title: Type
description: Record type. Either `CNAME`, `TXT` or `MX`.
example: CNAME
name:
type: string
title: Name
description: Host the record goes on.
example: em1234.example.com
value:
type: string
title: Value
description: Value to publish.
example: u1234567.wl123.sendgrid.net
ttl:
type: integer
title: Ttl
description: Time to live to publish the record with, in seconds.
default: 300
example: 300
status:
anyOf:
- type: string
- type: 'null'
title: Status
description: >-
Whether Base44 can see the record yet. Either `pending`, `verified`
or `failed`. The value is `null` before the first check.
example: pending
type: object
required:
- type
- name
- value
title: EmailDnsRecordResponse
description: DNS record for email configuration.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````