> ## 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.
# Enable email sending for a domain
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Turns on email sending from a domain the app already owns, so mail leaves as your address instead of Base44's.
The domain has to be connected to the app first, and ready: a domain you brought yourself must be verified, and one bought through Base44 must have finished propagating. Either way you get a 412 until it is, and the message says which.
What happens next depends on who runs the domain's DNS. When Base44 can write the records itself it does, and the domain moves toward verification on its own. Otherwise you get the records to publish in `dns_records`, and the domain waits at `pending_user_dns_configuration` until they resolve. Records are always returned, so you can show them either way.
An app sends from one domain at a time. If one is already set up you get a 409, whatever state it is in, so disable it first or use [Replace the email domain](/api-reference/replace-the-email-domain), which keeps sending going while the new domain verifies.
Turning a domain back on after you disabled it is the exception: it comes back in the state it was in, so a domain that was sending resumes at once.
Otherwise sending is not live when this returns. Read `status`, and poll [List email domains](/api-reference/list-email-domains) until `configuration_status` reads `active`.
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
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:
post:
summary: Enable email sending for a domain
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Turns on email sending from a domain the app already owns, so mail
leaves as your address instead of Base44's.
The domain has to be connected to the app first, and ready: a domain you
brought yourself must be verified, and one bought through Base44 must
have finished propagating. Either way you get a 412 until it is, and the
message says which.
What happens next depends on who runs the domain's DNS. When Base44 can
write the records itself it does, and the domain moves toward
verification on its own. Otherwise you get the records to publish in
`dns_records`, and the domain waits at `pending_user_dns_configuration`
until they resolve. Records are always returned, so you can show them
either way.
An app sends from one domain at a time. If one is already set up you get
a 409, whatever state it is in, so disable it first or use [Replace the
email domain](/api-reference/replace-the-email-domain), which keeps
sending going while the new domain verifies.
Turning a domain back on after you disabled it is the exception: it
comes back in the state it was in, so a domain that was sending resumes
at once.
Otherwise sending is not live when this returns. Read `status`, and poll
[List email domains](/api-reference/list-email-domains) until
`configuration_status` reads `active`.
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: create_email_domain_api_apps__app_id__custom_email_domains_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/CreateEmailDomainRequest'
responses:
'200':
description: Setup started. Read `status` and `dns_records`.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailDomainResponse'
'400':
description: This domain cannot send mail.
'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, or you
used a workspace API key.
'404':
description: This domain is not connected to this app.
'409':
description: >-
This app already has an email domain set up, whether or not it is
sending yet. Disable it first, or use Replace the email domain.
'412':
description: >-
The 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:
CreateEmailDomainRequest:
properties:
domain:
type: string
title: Domain
description: >-
Domain to send mail from. It has to already be connected to this
app.
example: 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. Its domain has to be the `domain` you are
enabling.
example: no-reply@example.com
type: object
required:
- domain
- sender_name
- from_email
title: CreateEmailDomainRequest
description: Request to create email domain configuration.
CreateEmailDomainResponse:
properties:
domain:
type: string
title: Domain
description: The domain that was enabled.
example: example.com
status:
type: string
title: Status
description: Where setup got to. Sending starts only at `active`.
example: pending_user_dns_configuration
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 domain yourself, `false` when it was
bought through Base44.
default: false
example: true
dns_records:
anyOf:
- items:
$ref: '#/components/schemas/EmailDnsRecordResponse'
type: array
- type: 'null'
title: Dns Records
description: >-
Records to publish for this domain. Always returned, including when
Base44 publishes them for you, so you can show a caller what was
set.
example:
- name: em1234.example.com
status: pending
ttl: 300
type: CNAME
value: u1234567.wl123.sendgrid.net
provider_id:
anyOf:
- type: string
- type: 'null'
title: Provider Id
description: >-
Identifier for the registrar the domain sits with, when Base44 knows
it.
example: godaddy
type: object
required:
- domain
- status
- email_domain_id
title: CreateEmailDomainResponse
description: Response for creating email domain configuration.
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.
````