> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailglyph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or find sending domain

> Idempotently create a sending domain and retrieve its required DNS records.



## OpenAPI

````yaml openapi.json POST /v1/domains
openapi: 3.0.3
info:
  title: MailGlyph API
  description: >-
    Email platform API for transactional emails, campaigns, and marketing
    automation
  version: 1.0.0
  contact:
    name: MailGlyph Support
    url: https://mailglyph.com
servers:
  - url: https://api.mailglyph.com
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Public API
    description: Public API endpoints for sending emails and tracking events
  - name: Events
    description: Event ingestion and querying
  - name: Contacts
    description: Contact management operations
  - name: Templates
    description: Email template management
  - name: Campaigns
    description: Email campaign management
  - name: Segments
    description: Audience segmentation
  - name: Workflows
    description: Workflow automation
paths:
  /v1/domains:
    post:
      tags:
        - Domains
      summary: Create or find a sending domain
      description: >-
        Idempotently create a sending domain in the API key's workspace. Domain
        names are normalized to lowercase. An all-domain secret key is required
        when the domain does not already exist.
      operationId: createDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  format: hostname
                  description: >-
                    Exact sending domain or subdomain. Wildcards, IP addresses,
                    and local hostnames are rejected.
                  example: portal.example.com
      responses:
        '200':
          description: Existing domain returned
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/PublicDomain'
        '201':
          description: Domain created
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/PublicDomain'
        '403':
          description: The key cannot create the domain or the workspace cannot add domains
        '409':
          description: The domain is already registered to another workspace
        '422':
          description: Invalid domain name
components:
  schemas:
    PublicDomain:
      type: object
      required:
        - id
        - domain
        - providerStatus
        - providerVerified
        - dnsReady
        - lastCheckedAt
        - records
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        domain:
          type: string
          format: hostname
          example: portal.example.com
        providerStatus:
          type: string
          enum:
            - pending
            - verified
            - failed
          description: Current AWS SES DKIM verification state.
        providerVerified:
          type: boolean
          description: Whether AWS SES has verified the domain's DKIM identity.
        dnsReady:
          type: boolean
          description: >-
            True when the required DKIM, MAIL FROM MX, and MAIL FROM SPF records
            are verified. DMARC is recommended but does not block readiness.
        lastCheckedAt:
          type: string
          format: date-time
          nullable: true
        records:
          type: array
          items:
            $ref: '#/components/schemas/DomainDnsRecord'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DomainDnsRecord:
      type: object
      required:
        - type
        - name
        - value
        - required
        - verified
      properties:
        type:
          type: string
          enum:
            - TXT
            - MX
        name:
          type: string
          example: mailglyph._domainkey.portal.example.com
        value:
          type: string
          example: p=MIIBIjANBgkqh...
        priority:
          type: integer
          minimum: 0
          nullable: true
        required:
          type: boolean
          description: Whether this record must verify before dnsReady becomes true.
        verified:
          type: boolean
          nullable: true
          description: >-
            Whether the record was present at the latest check. Null means it
            has not been checked yet.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API Key authentication. **Secret keys (sk_*)** are required for all
        endpoints except `/v1/track`. **Public keys (pk_*)** only work with the
        `/v1/track` endpoint for client-side event tracking. Workspaces can have
        multiple active keys, and sender-domain operations enforce per-key
        domain scope when configured.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.