openapi: 3.0.3
info:
  title: Mailhook API
  description: |
    Programmable temp inboxes for AI agents and developers.

    ## Authentication

    All API requests require authentication via headers:
    - `X-Agent-ID`: Your agent identifier
    - `X-API-Key`: Your API key

    Alternatively, use OAuth2 Bearer tokens for user-context requests.

    ## Base URL

    All API endpoints are relative to `https://app.mailhook.co/api/v1`

  version: 1.0.0
  contact:
    email: support@mailhook.co
    url: https://mailhook.co

servers:
  - url: https://app.mailhook.co/api/v1
    description: Production server

security:
  - AgentAuth: []
  - OAuth2: []

tags:
  - name: Agents
    description: Agent registration and management
  - name: Domains
    description: Manage custom email domains
  - name: Email Addresses
    description: Create and manage email inboxes
  - name: Inbound Emails
    description: Retrieve received emails
  - name: Webhooks
    description: Configure webhook endpoints
  - name: Outbound Emails
    description: Send emails (Business tier and above)
  - name: Email Verifications
    description: Verify email address validity and deliverability (Pro tier and above)

paths:
  /agents/register:
    post:
      tags: [Agents]
      summary: Register a new agent
      description: Create a new agent and receive API credentials
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional agent name
                  example: "My AI Agent"
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      agent_id:
                        type: string
                        example: "mh_abc123"
                      api_key:
                        type: string
                        example: "mh_live_..."
                      tier:
                        type: string
                        enum: [free, pro, business, enterprise]
                        example: "free"
                      daily_limit:
                        type: integer
                        example: 50
                      message:
                        type: string
                        example: "Agent registered successfully. Store your api_key securely - it cannot be retrieved later."

  /agents/onboard:
    post:
      tags: [Agents]
      summary: One-click agent onboarding
      description: |
        Creates everything an AI agent needs in a single call:
        - Account with API credentials
        - Shared domain (instantly verified)
        - Random email address with monitoring instructions

        This is the fastest way to get started. No authentication required.
        The response includes everything needed to start receiving emails immediately.

        **Email Retention:** Email addresses are automatically deleted based on your tier:
        - Free: 7 days
        - Pro ($99/mo): 30 days
        - Business ($300/mo): 90 days
        - Enterprise ($1000/mo): Unlimited
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional agent/account name
                  example: "My AI Agent"
                metadata:
                  type: object
                  description: Optional metadata to attach to the email address
                  example: {"purpose": "signup-verification", "project": "demo"}
      responses:
        '201':
          description: Agent fully onboarded with domain and email
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      agent_id:
                        type: string
                        description: Your unique agent identifier
                        example: "mh_abc123xyz..."
                      api_key:
                        type: string
                        description: Your API key - store securely!
                        example: "Abc123XyzSecretKey..."
                      tier:
                        type: string
                        example: "free"
                      daily_limit:
                        type: integer
                        example: 100
                      domain:
                        type: object
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                            example: "teal-dolphin-847.tail.me"
                          full_domain:
                            type: string
                            example: "teal-dolphin-847.tail.me"
                          slug:
                            type: string
                            example: "teal-dolphin-847"
                          ready:
                            type: boolean
                            example: true
                      email_address:
                        type: object
                        properties:
                          id:
                            type: string
                            example: "ea_abc123"
                          email:
                            type: string
                            format: email
                            example: "x7km2pq9wr@teal-dolphin-847.tail.me"
                          local_part:
                            type: string
                            example: "x7km2pq9wr"
                          metadata:
                            type: object
                          monitoring:
                            type: object
                            description: Instructions for monitoring incoming emails
                            properties:
                              poll:
                                type: object
                                description: Polling configuration
                              stream:
                                type: object
                                description: SSE streaming info (Pro tier)
                              ai_instruction:
                                type: string
                                description: Step-by-step instructions for AI agents
                      message:
                        type: string
                        example: "Agent onboarded successfully!"
                      next_steps:
                        type: array
                        items:
                          type: string
                  upgrade:
                    type: object
                    description: Upgrade information (for free tier accounts)
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /agents/me:
    get:
      tags: [Agents]
      summary: Get current agent info
      description: Returns information about the authenticated agent
      responses:
        '200':
          description: Agent information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'

    delete:
      tags: [Agents]
      summary: Delete agent
      description: Permanently delete the authenticated agent and all associated data
      responses:
        '200':
          description: Agent deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Account deleted"

  /agents/status:
    get:
      tags: [Agents]
      summary: Poll upgrade checkout status
      description: Returns the status of a pending Stripe checkout upgrade. Requires a polling token from the upgrade endpoint.
      security: []
      parameters:
        - name: token
          in: query
          required: true
          description: Polling token returned by POST /agents/upgrade
          schema:
            type: string
      responses:
        '200':
          description: Upgrade checkout status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [pending, completed, expired]
                  target_tier:
                    type: string
                    enum: [pro, business, enterprise]
                  expires_at:
                    type: string
                    format: date-time
                  time_remaining:
                    type: integer
                    description: Seconds remaining before checkout expires

  /domains:
    get:
      tags: [Domains]
      summary: List domains
      description: Returns all domains for the authenticated agent
      responses:
        '200':
          description: List of domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainList'

    post:
      tags: [Domains]
      summary: Create domain
      description: Add a new domain (shared domains available on all tiers, custom domains require Enterprise)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: "inbox.example.com"
      responses:
        '201':
          description: Domain created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '403':
          description: Plan upgrade required

  /domains/{id}:
    get:
      tags: [Domains]
      summary: Get domain
      description: Returns details for a specific domain
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Domain details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'

    delete:
      tags: [Domains]
      summary: Delete domain
      description: Remove a domain and all associated email addresses
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Domain deleted

  /domains/{id}/verify:
    post:
      tags: [Domains]
      summary: Verify domain
      description: Trigger DNS verification for a domain
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verified:
                        type: boolean
                      mx_record:
                        type: boolean
                      txt_record:
                        type: boolean

  /domains/{id}/dns_records:
    get:
      tags: [Domains]
      summary: Get DNS records
      description: Returns required DNS records for domain verification
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: DNS records
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      mx:
                        type: object
                        properties:
                          host:
                            type: string
                          value:
                            type: string
                          priority:
                            type: integer
                      txt:
                        type: object
                        properties:
                          host:
                            type: string
                          value:
                            type: string

  /email_addresses:
    get:
      tags: [Email Addresses]
      summary: List email addresses
      description: Returns all email addresses for the authenticated agent
      responses:
        '200':
          description: List of email addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressList'

    post:
      tags: [Email Addresses]
      summary: Create email address
      description: Create a new email address with a specific local part
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain_id, local_part]
              properties:
                domain_id:
                  type: string
                  description: Domain ID to create address on
                local_part:
                  type: string
                  description: Local part of the email address
                  example: "support"
                metadata:
                  type: object
                  description: Custom metadata to attach
      responses:
        '201':
          description: Email address created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'

  /email_addresses/random:
    post:
      tags: [Email Addresses]
      summary: Create random email address
      description: Create a new email address with a random local part
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain_id]
              properties:
                domain_id:
                  type: string
                  description: Domain ID to create address on
                metadata:
                  type: object
                  description: Custom metadata to attach
      responses:
        '201':
          description: Random email address created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'

  /email_addresses/batch:
    post:
      tags: [Email Addresses, Batch Operations]
      summary: Create multiple email addresses (Pro)
      description: Create multiple email addresses in a single API call. Requires Pro tier or higher. Max 50-500 items depending on tier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email_addresses]
              properties:
                email_addresses:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    required: [domain_id, local_part]
                    properties:
                      domain_id:
                        type: string
                      local_part:
                        type: string
                      metadata:
                        type: object
                      expires_at:
                        type: string
                        format: date-time
      responses:
        '201':
          description: All email addresses created successfully
        '207':
          description: Partial success - some addresses created, some failed
        '403':
          description: Pro tier required
    delete:
      tags: [Email Addresses, Batch Operations]
      summary: Delete multiple email addresses (Pro)
      description: Delete multiple email addresses in a single API call. Requires Pro tier or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ids]
              properties:
                ids:
                  type: array
                  items:
                    type: string
                  description: Array of email address IDs to delete
      responses:
        '200':
          description: Deletion results
        '403':
          description: Pro tier required

  /email_addresses/batch_random:
    post:
      tags: [Email Addresses, Batch Operations]
      summary: Create multiple random email addresses (Pro)
      description: Create multiple email addresses with random local parts. Requires Pro tier or higher. Max 50 items.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain_id, count]
              properties:
                domain_id:
                  type: string
                  description: Domain ID to create addresses on
                count:
                  type: integer
                  minimum: 1
                  maximum: 50
                  description: Number of addresses to create
                metadata:
                  type: object
                  description: Metadata to attach to all created addresses
                prefix:
                  type: string
                  description: Optional prefix for the random local parts
      responses:
        '201':
          description: Random email addresses created
        '403':
          description: Pro tier required

  /inbound_emails/batch:
    get:
      tags: [Inbound Emails, Batch Operations]
      summary: Fetch emails from multiple inboxes (Pro)
      description: Retrieve inbound emails from multiple email addresses in a single request. Requires Pro tier or higher. Max 20 inboxes.
      parameters:
        - name: email_address_ids[]
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: Array of email address IDs to fetch from (max 20)
        - name: since
          in: query
          schema:
            type: string
            format: date-time
          description: Only return emails received after this timestamp
        - name: unread
          in: query
          schema:
            type: boolean
          description: Only return unread emails
      responses:
        '200':
          description: Batch email retrieval results
        '403':
          description: Pro tier required
    delete:
      tags: [Inbound Emails, Batch Operations]
      summary: Delete multiple emails (Pro)
      description: Delete multiple inbound emails in a single request. Requires Pro tier or higher. Max 500 items.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of email IDs to delete
                email_address_id:
                  type: string
                  description: Delete all emails from this inbox (requires all=true)
                all:
                  type: boolean
                  description: Delete all emails matching criteria
                before:
                  type: string
                  format: date-time
                  description: Only delete emails received before this timestamp
      responses:
        '200':
          description: Deletion results
        '403':
          description: Pro tier required

  /inbound_emails/batch_mark_read:
    patch:
      tags: [Inbound Emails, Batch Operations]
      summary: Mark multiple emails as read (Pro)
      description: Mark multiple inbound emails as read in a single request. Requires Pro tier or higher. Max 500 items.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of email IDs to mark as read
                email_address_id:
                  type: string
                  description: Mark all emails in this inbox as read (requires all=true)
                all:
                  type: boolean
                  description: Mark all emails matching criteria as read
                since:
                  type: string
                  format: date-time
                  description: Only mark emails received after this timestamp
      responses:
        '200':
          description: Update results
        '403':
          description: Pro tier required

  /email_addresses/{id}:
    get:
      tags: [Email Addresses]
      summary: Get email address
      description: Returns details for a specific email address
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Email address details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'

    patch:
      tags: [Email Addresses]
      summary: Update email address
      description: Update metadata for an email address
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
      responses:
        '200':
          description: Email address updated

    delete:
      tags: [Email Addresses]
      summary: Delete email address
      description: Remove an email address and all associated emails
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Email address deleted

  /email_addresses/{id}/inbound_emails:
    get:
      tags: [Inbound Emails]
      summary: List inbound emails
      description: Returns emails received at a specific address
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: since
          in: query
          description: Only return emails received after this timestamp
          schema:
            type: string
            format: date-time
        - name: unread
          in: query
          description: Only return unread emails
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum number of emails to return
          schema:
            type: integer
            default: 50
            maximum: 100
      responses:
        '200':
          description: List of inbound emails
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundEmailList'

  /email_addresses/{email_id}/inbound_emails/{id}:
    get:
      tags: [Inbound Emails]
      summary: Get inbound email
      description: Returns a specific inbound email with full content
      parameters:
        - name: email_id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Inbound email details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundEmail'

  /email_addresses/{email_id}/inbound_emails/{id}/mark_read:
    patch:
      tags: [Inbound Emails]
      summary: Mark email as read
      description: Mark an inbound email as read
      parameters:
        - name: email_id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Email marked as read

  /email_addresses/{id}/stream:
    get:
      tags: [Inbound Emails]
      summary: Stream emails (SSE)
      description: |
        Server-Sent Events stream for real-time email notifications.
        Requires Pro tier or above.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SSE stream
          content:
            text/event-stream:
              schema:
                type: string
        '403':
          description: Plan upgrade required

  /webhooks:
    get:
      tags: [Webhooks]
      summary: List webhooks
      description: Returns all webhook configurations
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'

    post:
      tags: [Webhooks]
      summary: Create webhook
      description: Create a new webhook endpoint (requires Pro tier or above)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  example: "https://example.com/webhook"
                events:
                  type: array
                  items:
                    type: string
                    enum: [email.received, email.bounced]
                email_address_id:
                  type: string
                  description: Optional - limit to specific email address
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'

  /webhooks/{id}:
    get:
      tags: [Webhooks]
      summary: Get webhook
      description: Returns details for a specific webhook
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'

    patch:
      tags: [Webhooks]
      summary: Update webhook
      description: Update webhook configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                enabled:
                  type: boolean
      responses:
        '200':
          description: Webhook updated

    delete:
      tags: [Webhooks]
      summary: Delete webhook
      description: Remove a webhook configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted

  /webhooks/{id}/test:
    post:
      tags: [Webhooks]
      summary: Test webhook
      description: Send a test payload to the webhook endpoint
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                      status_code:
                        type: integer
                      response_time_ms:
                        type: integer

  /outbound_emails:
    post:
      tags: [Outbound Emails]
      summary: Send email
      description: Send an outbound email (requires Business tier or above)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email_address_id, to, subject]
              properties:
                email_address_id:
                  type: string
                  description: Email address ID to send from
                to:
                  type: string
                  format: email
                  description: Recipient email address
                subject:
                  type: string
                text_body:
                  type: string
                html_body:
                  type: string
      responses:
        '201':
          description: Email queued for sending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundEmail'
        '403':
          description: Plan upgrade required

  /outbound_emails/{id}:
    get:
      tags: [Outbound Emails]
      summary: Get outbound email
      description: Returns details and delivery status for an outbound email
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Outbound email details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundEmail'

  /email_verifications:
    post:
      tags: [Email Verifications]
      summary: Verify an email address
      description: |
        Verify whether an email address is valid and deliverable without sending a message.

        - `quick` (default): syntax + MX + disposable/role/free-provider checks. Runs synchronously,
          costs **1** quota unit.
        - `full`: additionally checks SMTP mailbox deliverability (catch-all, deliverable, disabled).
          Runs asynchronously — poll the returned id with GET /email_verifications/{id}. Costs **1** quota unit.
          **Business tier and above only**; requesting `full` on Pro returns `403`.

        The `verdict` field is one of `valid`, `risky`, `invalid`, `unknown` (mirrors Reacher's `is_reachable`).
        In `quick` mode, `valid` means syntactically valid and the domain accepts mail — mailbox existence
        is not verified. Results are cached for 5 minutes per email+mode.

        Returns `402` when the monthly verification quota is exceeded, `403` when the feature is not on the plan
        or when `full` mode is requested on a plan below Business.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                mode:
                  type: string
                  enum: [quick, full]
                  default: quick
                sync:
                  type: boolean
                  default: true
                  description: Run quick checks synchronously (ignored for full mode)
      responses:
        '200':
          description: Returned a cached recent verification (within 5 minutes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerification'
        '201':
          description: Verification created (completed if quick+sync, otherwise pending)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerification'
        '400':
          description: Invalid email input
        '402':
          description: Monthly verification quota exceeded
        '403':
          description: Plan upgrade required (Pro tier and above)
    get:
      tags: [Email Verifications]
      summary: List verification history
      description: Returns the account's past verifications, most recent first (paginated).
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Paginated list of verifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailVerification'

  /email_verifications/{id}:
    get:
      tags: [Email Verifications]
      summary: Get verification result
      description: Poll a verification by its public id (prefixed `ev_`) to retrieve status and result.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: ev_abc12345
      responses:
        '200':
          description: Verification details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerification'
        '404':
          description: Verification not found

components:
  securitySchemes:
    AgentAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key authentication. Also requires `X-Agent-ID` header.

        Example:
        ```
        X-Agent-ID: ag_abc123
        X-API-Key: mk_live_...
        ```
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.mailhook.co/oauth/authorize
          tokenUrl: https://app.mailhook.co/oauth/token
          scopes:
            read: Read access to resources
            write: Write access to resources

  schemas:
    Agent:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              example: "mh_abc123"
            type:
              type: string
              example: "agent"
            attributes:
              type: object
              properties:
                name:
                  type: string
                tier:
                  type: string
                  enum: [free, pro, business, enterprise]
                daily_limit:
                  type: integer
                requests_remaining:
                  type: integer
                email_verification:
                  type: object
                  description: Monthly email-verification quota for the account.
                  properties:
                    quota:
                      type: integer
                      nullable: true
                      description: Monthly verification limit; null means unlimited.
                    used:
                      type: integer
                      description: Verifications used this calendar month.
                    remaining:
                      type: integer
                      description: Verifications remaining this month.
                created_at:
                  type: string
                  format: date-time

    Domain:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 5
            type:
              type: string
              example: "domain"
            attributes:
              type: object
              properties:
                name:
                  type: string
                  example: "my-agent.tail.me"
                domain_type:
                  type: string
                  enum: [shared, custom]
                tailme_slug:
                  type: string
                verification_status:
                  type: string
                  enum: [pending, verified, failed]
                provisioning_status:
                  type: string
                full_domain:
                  type: string
                ready:
                  type: boolean
                catch_all_enabled:
                  type: boolean
                email_addresses_count:
                  type: integer
                created_at:
                  type: string
                  format: date-time

    DomainList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Domain/properties/data'

    EmailAddress:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              example: "ea_abc123"
            type:
              type: string
              example: "email_address"
            attributes:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: "test123@inbox.mailhook.co"
                local_part:
                  type: string
                  example: "test123"
                domain_id:
                  type: integer
                domain:
                  type: string
                metadata:
                  type: object
                active:
                  type: boolean
                emails_received_count:
                  type: integer
                expires_at:
                  type: string
                  format: date-time
                  nullable: true
                created_at:
                  type: string
                  format: date-time
                updated_at:
                  type: string
                  format: date-time

    EmailAddressList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress/properties/data'

    InboundEmail:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 123
            type:
              type: string
              example: "inbound_email"
            attributes:
              type: object
              properties:
                from_email:
                  type: string
                  format: email
                from_name:
                  type: string
                subject:
                  type: string
                text_body:
                  type: string
                  description: Only present on single-email GET, not in list responses
                html_body:
                  type: string
                  description: Only present on single-email GET, not in list responses
                headers:
                  type: object
                  description: Only present on single-email GET, not in list responses
                attachments:
                  type: array
                  items:
                    type: object
                    properties:
                      filename:
                        type: string
                      content_type:
                        type: string
                      size:
                        type: integer
                      url:
                        type: string
                        format: uri
                read:
                  type: boolean
                received_at:
                  type: string
                  format: date-time

    InboundEmailList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/InboundEmail/properties/data'

    Webhook:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 1
            type:
              type: string
              example: "webhook"
            attributes:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                active:
                  type: boolean
                secret:
                  type: string
                  description: HMAC-SHA256 signing secret (only returned on create)
                email_address_id:
                  type: integer
                consecutive_failures:
                  type: integer
                last_success_at:
                  type: string
                  format: date-time
                  nullable: true
                last_failure_at:
                  type: string
                  format: date-time
                  nullable: true
                created_at:
                  type: string
                  format: date-time

    WebhookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook/properties/data'

    OutboundEmail:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 1
            type:
              type: string
              example: "outbound_email"
            attributes:
              type: object
              properties:
                from_email:
                  type: string
                  format: email
                to_email:
                  type: string
                  format: email
                subject:
                  type: string
                postmark_message_id:
                  type: string
                email_address_id:
                  type: integer
                status:
                  type: string
                  enum: [queued, sent, delivered, bounced, failed]
                sent_at:
                  type: string
                  format: date-time
                created_at:
                  type: string
                  format: date-time

    EmailVerification:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              example: "ev_abc12345"
            type:
              type: string
              example: "email_verification"
            attributes:
              type: object
              properties:
                email:
                  type: string
                  format: email
                mode:
                  type: string
                  enum: [quick, full]
                status:
                  type: string
                  enum: [pending, running, completed, failed]
                verdict:
                  type: string
                  enum: [valid, risky, invalid, unknown]
                  nullable: true
                result:
                  type: object
                  description: |
                    Structured sub-results. Includes `syntax`, `mx`, `disposable`, `role`, `free_provider`,
                    optional `suggestion`, and (full mode only) an `smtp` block with
                    `deliverable`/`catch_all`/`disabled`/`full_inbox`/`unknown`/`provider_result`.
                checks_performed:
                  type: array
                  items:
                    type: string
                completed:
                  type: boolean
                quota_units:
                  type: integer
                  example: 1
                created_at:
                  type: string
                  format: date-time
                updated_at:
                  type: string
                  format: date-time