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

# Generate an inbox address

> Inboxes are implicit: nothing is stored until mail arrives, and any address at an active domain already works. This endpoint exists so you don't have to reimplement our address format, and so the address you get back is guaranteed to be empty right now.

Omit `local_part` for a random address. Omit `domain` and you get a default — prefer passing it explicitly from `GET /api/v1/domains`.



## OpenAPI

````yaml https://api.meowmail.in/api/v1/openapi.json post /api/v1/inboxes
openapi: 3.1.0
info:
  title: MeowMail API
  version: 1.0.0
  summary: Free disposable email API. Receive-only, no accounts, TTL-expiring inboxes.
  description: >-
    Create throwaway inboxes and read the mail they receive.


    Built for automated testing of signup and verification flows, and for
    privacy tooling.


    **Inboxes are public.** There is no authorization on inbox contents: anyone
    who knows the address can read it. Never use MeowMail for anything you would
    mind a stranger reading, and never for password resets on accounts that
    matter.


    **Mail is ephemeral.** Emails are permanently deleted roughly one hour after
    arrival.


    **Receive-only.** There is no send endpoint and never will be in this API
    version.
  termsOfService: https://docs.meowmail.in/fair-use
  contact:
    name: MeowMail
    url: https://docs.meowmail.in
  license:
    name: Free to use under the fair-use policy
    url: https://docs.meowmail.in/fair-use
servers:
  - url: https://api.meowmail.in
    description: Production
security:
  - bearerAuth: []
  - apiKeyHeader: []
  - {}
tags:
  - name: Meta
    description: Discovery, spec, and health
  - name: Keys
    description: Free self-serve API keys
  - name: Domains
    description: Domains that accept mail
  - name: Inboxes
    description: Create inboxes and read their mail
  - name: Emails
    description: Individual emails and attachments
paths:
  /api/v1/inboxes:
    post:
      tags:
        - Inboxes
      summary: Generate an inbox address
      description: >-
        Inboxes are implicit: nothing is stored until mail arrives, and any
        address at an active domain already works. This endpoint exists so you
        don't have to reimplement our address format, and so the address you get
        back is guaranteed to be empty right now.


        Omit `local_part` for a random address. Omit `domain` and you get a
        default — prefer passing it explicitly from `GET /api/v1/domains`.
      operationId: createInbox
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  examples:
                    - meowmail.in
                local_part:
                  type: string
                  maxLength: 64
                  pattern: ^[a-z0-9][a-z0-9._+\-]{0,63}$
                  description: Optional. Lowercased. Random if omitted.
      responses:
        '201':
          description: Inbox address
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Inbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Inbox:
      type: object
      properties:
        address:
          type: string
          examples:
            - abc123@meowmail.in
        local_part:
          type: string
        domain:
          type: string
        email_ttl_seconds:
          type: integer
          description: How long an email survives after arrival.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - unauthorized
                - key_required
                - not_found
                - rate_limited
                - quota_exceeded
                - too_many_waiters
                - internal_error
              description: Stable machine-readable code. Branch on this, not on `message`.
            message:
              type: string
              description: Human-readable. May be reworded at any time.
            docs:
              type: string
  responses:
    BadRequest:
      description: Malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        Rate limit or daily quota exceeded, or too many long-polls already in
        flight for this key. Honour `retry-after`.
      headers:
        retry-after:
          schema:
            type: integer
          description: Seconds to wait.
        ratelimit-limit:
          schema:
            type: integer
        ratelimit-remaining:
          schema:
            type: integer
        ratelimit-reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer mm_...`. Omit entirely to use the anonymous tier.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to the Authorization header.

````