> ## 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.
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.
`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.
This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.
## 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.
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.
`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.
This endpoint accepts a personal API key. Workspace API keys are
not authorized for it and are rejected with a 403.
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 cannot 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 does not include custom domains.
'403':
description: >-
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':
description: >-
The new domain is not connected to this app, or the app has no email
domain to replace.
'412':
description: >-
The new domain is not ready yet: it still needs verifying, or its
DNS has not finished propagating.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (10 requests per minute).
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. The old one keeps sending until
this reads `active`.
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: >-
`true` when you brought the new domain yourself, `false` when it was
bought through Base44.
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.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
EmailDnsRecordResponse:
properties:
type:
type: string
title: Type
description: 'Record type: `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: `pending`, `verified` or
`failed`. `null` before the first check.
example: pending
type: object
required:
- type
- name
- value
title: EmailDnsRecordResponse
description: DNS record for email configuration.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````