openapi: 3.1.0
info:
  title: MailDrop Developer API
  version: 4.2.0
  summary: Account-only temporary email API for private testing inboxes.
  description: "Create private testing inboxes, read messages and OTP metadata, manage\
    \ signed webhook endpoints, and inspect account limits. Paid plan activation is\
    \ handled manually through WhatsApp and the MailDrop admin control plane.\n Developer\
    \ inbox domains are plan-controlled and discoverable through GET /domains. Team\
    \ workspaces use shared and personal resource scopes with role- and member-level\
    \ quotas."
  contact:
    name: MailDrop
    url: https://maildrop.online/developers.html
  license:
    name: MailDrop API Terms
    url: https://maildrop.online/terms.html
servers:
- url: https://api.maildrop.online/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Account
- name: Inboxes
- name: Messages
- name: Domains
  description: Plan-enabled domains available for developer inbox creation.
- name: Attachments
- name: Webhooks
- name: Team
  description: Workspace members, invitations, and ownership controls.
paths:
  /account:
    get:
      tags:
      - Account
      operationId: getAccount
      summary: Get authenticated account and plan
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  organization_id:
                    type: string
                  plan:
                    $ref: '#/components/schemas/Plan'
                  scopes:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /limits:
    get:
      tags:
      - Account
      operationId: getLimits
      summary: Get effective plan limits
      x-required-scope: usage:read
      responses:
        '200':
          description: Plan and limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  plan:
                    $ref: '#/components/schemas/Plan'
                  limits:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /usage:
    get:
      tags:
      - Account
      operationId: getUsage
      summary: Get current-month usage
      x-required-scope: usage:read
      responses:
        '200':
          description: Usage summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  usage:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /domains:
    get:
      tags:
      - Domains
      operationId: listDeveloperDomains
      summary: List developer domains available to the active plan
      x-required-scope: inboxes:read
      responses:
        '200':
          description: Plan-enabled developer domains
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeveloperDomain'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /inboxes:
    get:
      tags:
      - Inboxes
      operationId: listInboxes
      summary: List private inboxes
      x-required-scope: inboxes:read
      parameters:
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Inbox list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Inbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Inboxes
      operationId: createInbox
      summary: Create private inbox
      x-required-scope: inboxes:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInboxRequest'
      responses:
        '201':
          description: Inbox created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    $ref: '#/components/schemas/Inbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /inboxes/{inbox_id}:
    parameters:
    - $ref: '#/components/parameters/InboxId'
    get:
      tags:
      - Inboxes
      operationId: getInbox
      summary: Get private inbox
      x-required-scope: inboxes:read
      responses:
        '200':
          description: Inbox
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    $ref: '#/components/schemas/Inbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Inboxes
      operationId: deleteInbox
      summary: Delete private inbox
      x-required-scope: inboxes:write
      responses:
        '200':
          description: Inbox deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /inboxes/{inbox_id}/messages:
    parameters:
    - $ref: '#/components/parameters/InboxId'
    - $ref: '#/components/parameters/Limit'
    - $ref: '#/components/parameters/AfterId'
    get:
      tags:
      - Messages
      operationId: listMessages
      summary: List inbox messages
      x-required-scope: messages:read
      responses:
        '200':
          description: Messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  mailbox:
                    $ref: '#/components/schemas/Inbox'
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/MessageSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /messages/{message_id}:
    parameters:
    - $ref: '#/components/parameters/MessageId'
    get:
      tags:
      - Messages
      operationId: getMessage
      summary: Get full message and OTP metadata
      x-required-scope: messages:read
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Messages
      operationId: deleteMessage
      summary: Delete message
      x-required-scope: messages:delete
      responses:
        '200':
          description: Message deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                      id:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /messages/{message_id}/attachments:
    parameters:
    - $ref: '#/components/parameters/MessageId'
    get:
      tags:
      - Attachments
      operationId: listAttachments
      summary: List attachment metadata
      x-required-scope: attachments:read
      responses:
        '200':
          description: Attachments
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /webhooks:
    get:
      tags:
      - Webhooks
      operationId: listWebhooks
      summary: List webhook endpoints
      x-required-scope: webhooks:read
      responses:
        '200':
          description: Webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Webhooks
      operationId: createWebhook
      summary: Create signed webhook endpoint
      x-required-scope: webhooks:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Created; signing secret is returned once
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    allOf:
                    - $ref: '#/components/schemas/Webhook'
                    - type: object
                      properties:
                        secret:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /webhooks/{webhook_id}:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    patch:
      tags:
      - Webhooks
      operationId: updateWebhook
      summary: Update webhook endpoint
      x-required-scope: webhooks:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: object
                    properties:
                      updated:
                        type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhook
      summary: Delete webhook endpoint
      x-required-scope: webhooks:write
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  request_id:
                    type: string
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /webhooks/{webhook_id}/test:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    post:
      tags:
      - Webhooks
      operationId: testWebhook
      summary: Send signed webhook test
      x-required-scope: webhooks:write
      responses:
        '200':
          description: Delivery result
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Receiver failed or was unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /team:
    get:
      tags:
      - Team
      summary: List team state
      description: Requires team:read. Returns workspace identity, members, invitations,
        per-member effective limits, monthly API usage, and plan seats.
      responses:
        '200':
          description: Members, invitations, and plan limits.
      security:
      - ApiKeyAuth: []
  /team/invitations:
    post:
      tags:
      - Team
      summary: Create team invitation
      description: Requires team:write and an API key created by an active owner or
        admin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamInvitationRequest'
      responses:
        '201':
          description: One-time invitation link.
        '403':
          description: Insufficient scope or creator role.
      security:
      - ApiKeyAuth: []
  /team/invitations/{invitation_id}:
    delete:
      tags:
      - Team
      summary: Revoke team invitation
      parameters:
      - name: invitation_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invitation revoked.
      security:
      - ApiKeyAuth: []
  /team/members/{user_id}:
    patch:
      tags:
      - Team
      summary: Update team member
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamMemberRequest'
      responses:
        '200':
          description: Member updated.
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Team
      summary: Remove team member
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Member removed.
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: MailDrop API key
    maildropKey:
      type: apiKey
      in: header
      name: X-MailDrop-Key
  parameters:
    InboxId:
      name: inbox_id
      in: path
      required: true
      schema:
        type: integer
    MessageId:
      name: message_id
      in: path
      required: true
      schema:
        type: integer
    WebhookId:
      name: webhook_id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    AfterId:
      name: after_id
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Recommended for POST requests.
      schema:
        type: string
        minLength: 8
        maxLength: 128
  schemas:
    ApiError:
      type: object
      required:
      - success
      - error
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            details:
              type:
              - object
              - 'null'
              additionalProperties: true
    Plan:
      type:
      - object
      - 'null'
      additionalProperties: true
    Inbox:
      type: object
      required:
      - id
      - address
      - status
      - created_at
      properties:
        id:
          type: integer
        address:
          type: string
          format: email
        status:
          type: string
        visibility:
          type: string
        created_at:
          type: integer
          format: int64
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
        last_message_at:
          type:
          - integer
          - 'null'
          format: int64
        message_count:
          type:
          - integer
          - 'null'
        latest_otp:
          type:
          - string
          - 'null'
    MessageSummary:
      type: object
      properties:
        id:
          type: integer
        sender:
          type:
          - string
          - 'null'
        subject:
          type:
          - string
          - 'null'
        body_preview:
          type:
          - string
          - 'null'
        timestamp:
          type: integer
          format: int64
        has_otp:
          type:
          - integer
          - boolean
        otp_code:
          type:
          - string
          - 'null'
        otp_service:
          type:
          - string
          - 'null'
        attachment_count:
          type:
          - integer
          - 'null'
    Message:
      allOf:
      - $ref: '#/components/schemas/MessageSummary'
      - type: object
        properties:
          body:
            type:
            - string
            - 'null'
          mailbox_id:
            type: integer
          address:
            type: string
            format: email
    Attachment:
      type: object
      properties:
        id:
          type: integer
        filename:
          type:
          - string
          - 'null'
        content_type:
          type:
          - string
          - 'null'
        size_bytes:
          type:
          - integer
          - 'null'
        disposition:
          type:
          - string
          - 'null'
        content_id:
          type:
          - string
          - 'null'
        stored:
          type: boolean
        download_available:
          type: boolean
        download_note:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        status:
          type: string
        failure_count:
          type: integer
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
    CreateInboxRequest:
      type: object
      properties:
        local:
          type: string
          example: checkout-qa
        domain:
          type: string
          example: tests.maildrop.online
        lifetime_hours:
          type: integer
          minimum: 1
          maximum: 720
          example: 24
        access_scope:
          type: string
          enum:
          - personal
          - workspace
          default: personal
          description: Developers create personal inboxes by default. Workspace scope
            requires an owner/admin or explicit member permission.
    CreateWebhookRequest:
      type: object
      required:
      - url
      properties:
        name:
          type: string
          example: CI receiver
        url:
          type: string
          format: uri
          example: https://example.com/maildrop-events
        events:
          type: array
          items:
            type: string
            enum:
            - message.received
            - inbox.created
            - inbox.deleted
    UpdateWebhookRequest:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - disabled
    DeveloperDomain:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          format: hostname
          example: tests.maildrop.online
        label:
          type: string
          nullable: true
          example: QA testing
        description:
          type: string
          nullable: true
        is_default:
          type: boolean
        routing_ready:
          type: boolean
          description: Whether Cloudflare Email Routing has been confirmed by an administrator.
    TeamMember:
      type: object
      properties:
        user_id:
          type: string
        email:
          type: string
          format: email
        display_name:
          type: string
        role:
          type: string
          enum:
          - owner
          - admin
          - developer
          - viewer
        status:
          type: string
    TeamInvitation:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        status:
          type: string
        expires_at:
          type: integer
          format: int64
        invite_url:
          type: string
          format: uri
    CreateTeamInvitationRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        role:
          type: string
          enum:
          - admin
          - developer
          - viewer
          default: developer
        resource_mode:
          type: string
          enum:
          - shared
          - personal_only
          - read_only_shared
          default: shared
        permissions:
          $ref: '#/components/schemas/MemberPermissions'
        limits:
          $ref: '#/components/schemas/MemberLimits'
        expires_hours:
          type: integer
          minimum: 1
          maximum: 168
          default: 168
    UpdateTeamMemberRequest:
      type: object
      properties:
        action:
          type: string
          enum:
          - update
          - policy
          - transfer_owner
        role:
          type: string
          enum:
          - owner
          - admin
          - developer
          - viewer
        resource_mode:
          type: string
          enum:
          - shared
          - personal_only
          - read_only_shared
        permissions:
          $ref: '#/components/schemas/MemberPermissions'
        limits:
          $ref: '#/components/schemas/MemberLimits'
    MemberLimits:
      type: object
      description: Per-member caps. Missing values inherit the plan; zero disables
        the resource; values cannot exceed the plan.
      properties:
        max_active_inboxes:
          type: integer
          minimum: 0
        max_inbox_creations_per_hour:
          type: integer
          minimum: 0
        max_api_keys:
          type: integer
          minimum: 0
        max_webhook_endpoints:
          type: integer
          minimum: 0
        max_api_requests_per_minute:
          type: integer
          minimum: 0
        max_api_requests_per_month:
          type: integer
          minimum: 0
    MemberPermissions:
      type: object
      additionalProperties:
        type: boolean
      description: Optional capability overrides constrained by the member role.
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing, invalid, revoked, or expired API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Missing required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Resource not found or not owned
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate or monthly quota reached
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'