openmail-sh Owned Domains API

openapi: 3.2.0
info:
  title: OpenMail Owned Domains API
  description: Email infrastructure API for AI agents. Create inboxes, send and receive email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
- url: https://api.openmail.sh
security:
- bearerAuth: []
tags:
- name: owned-domains
  description: Domains your organisation controls but does not send from. Prove ownership with one TXT record and mail to their addresses stops counting toward the cold outreach limits.
paths:
  /v1/owned-domains:
    get:
      operationId: listOwnedDomains
      summary: List owned domains
      tags:
      - owned-domains
      description: List the domains your organisation has registered for ownership proof, verified or not.
      responses:
        '200':
          description: List of owned domains
          content:
            application/json:
              schema:
                description: List of owned domains
                type: object
                additionalProperties: true
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OwnedDomain'
        '401':
          description: Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                description: Missing, invalid, or expired API key
                allOf:
                - $ref: '#/components/schemas/Error'
    post:
      operationId: createOwnedDomain
      summary: Add owned domain
      tags:
      - owned-domains
      description: Register a domain your organisation controls but does not send from through OpenMail — your company's main domain, say, while your agents send from a subdomain. Once verified, recipients on it (and on any subdomain) do not count as new recipients for the cold outreach limits, so agents can write to your own staff freely. The response includes the one TXT record to publish; then call verify. Verified custom domains are covered automatically and do not need adding here. Account-wide key only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - domain
              properties:
                domain:
                  type: string
                  minLength: 4
                  maxLength: 253
                  description: The domain to prove ownership of, e.g. `acme.com`.
      responses:
        '201':
          description: Domain added; publish the TXT record, then verify
          content:
            application/json:
              schema:
                description: Domain added; publish the TXT record, then verify
                allOf:
                - $ref: '#/components/schemas/OwnedDomain'
        '403':
          description: The key is pod- or inbox-scoped (`forbidden`), or the account already has the maximum number of owned domains (`owned_domain_limit`)
          content:
            application/json:
              schema:
                description: The key is pod- or inbox-scoped (`forbidden`), or the account already has the maximum number of owned domains (`owned_domain_limit`)
                allOf:
                - $ref: '#/components/schemas/Error'
        '409':
          description: You already added this domain (`domain_exists`)
          content:
            application/json:
              schema:
                description: You already added this domain (`domain_exists`)
                allOf:
                - $ref: '#/components/schemas/Error'
        '422':
          description: Invalid domain (`invalid_domain`), one of OpenMail's own domains (`invalid_domain_reserved`), or a public email provider nobody can own (`domain_not_ownable`)
          content:
            application/json:
              schema:
                description: Invalid domain (`invalid_domain`), one of OpenMail's own domains (`invalid_domain_reserved`), or a public email provider nobody can own (`domain_not_ownable`)
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/owned-domains/{id}:
    get:
      operationId: getOwnedDomain
      summary: Get owned domain
      tags:
      - owned-domains
      description: Fetch one owned domain, including the TXT record to publish and its current status.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Owned domain details
          content:
            application/json:
              schema:
                description: Owned domain details
                allOf:
                - $ref: '#/components/schemas/OwnedDomain'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteOwnedDomain
      summary: Delete owned domain
      tags:
      - owned-domains
      description: Remove an owned domain. Recipients on it count as new recipients again from the next send. This does not remove the TXT record from your DNS.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '204':
          description: Owned domain deleted
        '403':
          description: The key is pod- or inbox-scoped (`forbidden`)
          content:
            application/json:
              schema:
                description: The key is pod- or inbox-scoped (`forbidden`)
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/owned-domains/{id}/verify:
    post:
      operationId: verifyOwnedDomain
      summary: Verify owned domain
      tags:
      - owned-domains
      description: Look up the TXT record now and update `status`. Call this after publishing the record. A resolver failure leaves the status unchanged rather than marking the domain failed.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Re-checked; the returned domain reflects the latest status
          content:
            application/json:
              schema:
                description: Re-checked; the returned domain reflects the latest status
                allOf:
                - $ref: '#/components/schemas/OwnedDomain'
        '403':
          description: The key is pod- or inbox-scoped (`forbidden`)
          content:
            application/json:
              schema:
                description: The key is pod- or inbox-scoped (`forbidden`)
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
components:
  schemas:
    OwnedDomain:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: Owned domain ID
        domain:
          type: string
          description: The domain your organisation controls, e.g. `acme.com`. Subdomains are covered too.
        status:
          type: string
          enum:
          - pending
          - verified
          - failed
          description: '`pending` — added, TXT record not yet seen. `verified` — recipients on this domain are not metered as cold outreach. `failed` — the record was verified before and has since disappeared; publish it again and call verify.'
        record:
          type: object
          description: The one TXT record to publish to prove ownership.
          properties:
            type:
              type: string
              enum:
              - TXT
            host:
              type: string
              description: Record name, e.g. `_openmail-owner.acme.com`
            value:
              type: string
              description: Record value, e.g. `openmail-owner=…`
        verifiedAt:
          type:
          - string
          - 'null'
          format: date-time
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the record was last looked up, whatever the result.
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key