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

> ## Agent Instructions
> Treat docs/openapi.yaml as the normative public API contract.
> Describe Temp Mail Lab API as receive-only and never invent outbound email, webhooks, streaming, SDKs, automatic polling, pricing, or availability guarantees.
> Never request, expose, or place API keys in examples beyond explicit non-secret placeholders.

# Create a temporary email

> Atomically reserves a new address for 30 days. Omit local_part and domain
to let the service select both, or provide either/both. The address starts
receiving through the isolated API mail system immediately after the
reservation becomes active; no website session, browser presence, or
dashboard availability is required.

Idempotency keys are scoped to the authenticated account and operation.
Replaying the same key and equivalent request returns the original resource
and is not charged again. Reusing a key with a different request returns
409. An address is never reallocated after expiry.




## OpenAPI

````yaml /docs/openapi.yaml post /v1/emails
openapi: 3.1.0
info:
  title: Temp Mail Lab API
  version: 0.1.0-draft
  summary: Receive-only temporary email API for Temp Mail Lab Premium customers.
  description: |
    Create isolated temporary email addresses and retrieve messages, raw RFC 822
    source, and attachments. This contract is a pre-launch draft.

    The API never sends email and never performs automatic polling. A client
    decides when to make each request, and every processed request follows the
    documented usage policy.
  contact:
    name: Temp Mail Lab
    url: https://tempmaillab.com
  license:
    name: Temp Mail Lab Terms of Service
    url: https://tempmaillab.com/terms
servers:
  - url: https://api.tempmaillab.com
    description: Production (available only after the approved public launch)
security:
  - bearerAuth: []
tags:
  - name: Domains
    description: Discover domains that can create and receive API email.
  - name: Emails
    description: Create and inspect isolated temporary email reservations.
  - name: Messages
    description: List and retrieve received messages and their private content.
  - name: Usage
    description: Inspect the authenticated account's current request allowance.
paths:
  /v1/emails:
    post:
      tags:
        - Emails
      summary: Create a temporary email
      description: >
        Atomically reserves a new address for 30 days. Omit local_part and
        domain

        to let the service select both, or provide either/both. The address
        starts

        receiving through the isolated API mail system immediately after the

        reservation becomes active; no website session, browser presence, or

        dashboard availability is required.


        Idempotency keys are scoped to the authenticated account and operation.

        Replaying the same key and equivalent request returns the original
        resource

        and is not charged again. Reusing a key with a different request returns

        409. An address is never reallocated after expiry.
      operationId: createEmail
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailRequest'
            examples:
              automatic:
                summary: Let the service choose the name and domain
                value: {}
              custom:
                summary: Request a custom name and domain
                value:
                  local_part: checkout-test-42
                  domain: mail.example.com
      responses:
        '201':
          description: >-
            The email was created, or the original successful creation was
            replayed.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
            Location:
              description: Relative path of the created resource.
              schema:
                type: string
              example: /v1/emails/eml_4p9g2t7n8w
            Cache-Control:
              $ref: '#/components/headers/PrivateNoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        '400':
          $ref: '#/components/responses/BadRequestCharged'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/ConflictCharged'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableCharged'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        Unique caller-generated value for safely retrying this creation. It is
        scoped to the authenticated account and operation and must not contain a
        secret or API key.
      schema:
        type: string
        minLength: 16
        maxLength: 255
        pattern: ^[\x21-\x7E]+$
  schemas:
    CreateEmailRequest:
      type: object
      additionalProperties: false
      properties:
        local_part:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$
          description: >
            Optional lowercase custom name. The server normalizes and validates
            it,

            rejects reserved names, and never reallocates a previously issued
            name.
        domain:
          type: string
          format: hostname
          maxLength: 253
          description: Optional active domain returned by GET /v1/domains.
    EmailResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Email'
    Email:
      type: object
      additionalProperties: false
      required:
        - id
        - address
        - local_part
        - domain
        - status
        - created_at
        - expires_at
      properties:
        id:
          $ref: '#/components/schemas/EmailId'
        address:
          type: string
          format: email
        local_part:
          type: string
        domain:
          type: string
          format: hostname
        status:
          type: string
          enum:
            - active
            - expired
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: The reservation stops receiving 30 days after creation.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    EmailId:
      type: string
      pattern: ^eml_[A-Za-z0-9_-]{10,64}$
      examples:
        - eml_4p9g2t7n8w
    ErrorObject:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          pattern: ^[a-z][a-z0-9_]{2,63}$
        message:
          type: string
        request_id:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
        - reason
      properties:
        field:
          type: string
        reason:
          type: string
  headers:
    RequestId:
      description: Opaque request identifier for support and audit correlation.
      required: true
      schema:
        type: string
        pattern: ^req_[A-Za-z0-9_-]{16,80}$
    RateLimitLimit:
      description: >-
        Current authoritative request allowance visible to this key. Separate
        short-window safety limits may reject bursts with 429.
      required: true
      schema:
        type: integer
        minimum: 0
    RateLimitRemaining:
      description: Requests remaining in the current authoritative allowance window.
      required: true
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: >-
        UTC Unix timestamp when the current authoritative allowance window
        resets.
      required: true
      schema:
        type: integer
        minimum: 0
    IdempotencyReplayed:
      description: >-
        True when this response replays a previous successful request and is not
        charged again.
      required: true
      schema:
        type: boolean
    PrivateNoStore:
      description: Sensitive API responses must not be stored by shared or browser caches.
      required: true
      schema:
        type: string
        const: private, no-store
    RetryAfter:
      description: Seconds until the client may retry.
      required: true
      schema:
        type: integer
        minimum: 1
  responses:
    BadRequestCharged:
      description: >-
        Authenticated request could not be processed because its syntax or
        parameters are invalid. Charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidCursor:
              value:
                error:
                  code: invalid_request
                  message: The request parameters are invalid.
                  request_id: req_a1b2c3d4e5f6g7h8
                  details:
                    - field: cursor
                      reason: invalid
    Unauthorized:
      description: >-
        Missing, malformed, revoked, or environment-invalid API key. Not
        charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidKey:
              value:
                error:
                  code: invalid_api_key
                  message: A valid API key is required.
                  request_id: req_a1b2c3d4e5f6g7h8
    Forbidden:
      description: >-
        Authenticated account is not entitled to the requested operation. Not
        charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ConflictCharged:
      description: >-
        The requested state conflicts with an existing reservation or
        idempotency record. Charged unless it is an exact replay.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: The request body exceeds the gateway's accepted size. Not charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableCharged:
      description: >-
        Request is syntactically valid but violates address or domain policy.
        Charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        A short-window safety or authoritative quota limit was reached. Not
        charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests. Retry after the indicated delay.
                  request_id: req_a1b2c3d4e5f6g7h8
    ServerError:
      description: >-
        The service failed before completing the operation. Not charged; never
        represented as an empty success.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        A required isolated API dependency is temporarily unavailable. Not
        charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        Cache-Control:
          $ref: '#/components/headers/PrivateNoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tml_live_...
      description: >
        Send a live API key in the Authorization header. Keys in query strings
        are

        rejected. A staging key never authenticates against production.

````