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

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Turns on email sending from a domain the app already owns, so your app's email comes from your own 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. Until then the call fails, and the message says which requirement is missing.

An app sends emails from one domain at a time. If one is already set up, this call is rejected whatever state that domain is in. Disable it first, or use [Replace the email domain](/api-reference/replace-the-email-domain), which keeps the current domain sending while the new one verifies.

Email isn't live when this returns. The domain still needs DNS records in place, and who publishes them depends on who runs its DNS:

- When Base44 runs the DNS, it writes the records itself and the domain moves toward verification on its own.
- When you run the DNS, publish the records yourself. The domain waits at `pending_user_dns_configuration` until they resolve.

Either way the records come back in `dns_records`, so you can pass them to whoever manages the domain's DNS.

Poll [List email domains](/api-reference/list-email-domains) until `configuration_status` reads `active`, which is when mail starts sending.

Turning a domain back on after you disabled it skips the DNS and verification steps. It returns to the state it was in, so a domain that was already sending resumes at once.



## 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: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Turns on email sending from a domain the app already owns, so your app's
        email comes from your own 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. Until then the call fails, and the message
        says which requirement is missing.


        An app sends emails from one domain at a time. If one is already set up,
        this call is rejected whatever state that domain is in. Disable it
        first, or use [Replace the email
        domain](/api-reference/replace-the-email-domain), which keeps the
        current domain sending while the new one verifies.


        Email isn't live when this returns. The domain still needs DNS records
        in place, and who publishes them depends on who runs its DNS:


        - When Base44 runs the DNS, it writes the records itself and the domain
        moves toward verification on its own.

        - When you run the DNS, publish the records yourself. The domain waits
        at `pending_user_dns_configuration` until they resolve.


        Either way the records come back in `dns_records`, so you can pass them
        to whoever manages the domain's DNS.


        Poll [List email domains](/api-reference/list-email-domains) until
        `configuration_status` reads `active`, which is when mail starts
        sending.


        Turning a domain back on after you disabled it skips the DNS and
        verification steps. It returns to the state it was in, so a domain that
        was already sending resumes at once.
      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 can't send mail.
        '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: This domain isn't connected to this app, or the app doesn't exist.
        '409':
          description: >-
            This app already has an email domain set up, whether or not it's
            sending yet. Disable it first, or use [Replace the email
            domain](/api-reference/replace-the-email-domain).
        '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:
    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're
            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. Only `active` sends mail. 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_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: >-
            Whether you brought the domain yourself (`true`) or bought it
            through Base44 (`false`).
          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. They come back even when Base44
            publishes them for you, so you can pass them to whoever manages the
            domain's DNS.
          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.
    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.

````