AgentMail Agent API

openapi: 3.2.0
info:
  title: Reference Agent API
  version: 1.0.0
servers:
- url: https://api.agentmail.to
  description: prod
- url: https://x402.api.agentmail.to
  description: prod-x402
- url: https://mpp.api.agentmail.to
  description: prod-mpp
- url: https://api.agentmail.eu
  description: eu-prod
tags:
- name: Agent
paths:
  /v0/agent/sign-up:
    post:
      operationId: sign-up
      summary: Sign Up
      description: 'Create a new agent organization with an inbox and API key. This endpoint is for signing up for the first time. If you''ve already signed up, you''re all set — just use your existing API key.


        A 6-digit OTP is sent to the human''s email for verification.


        This endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the OTP if expired.


        The returned API key has limited permissions until the organization is verified via the verify endpoint.


        **CLI:**

        ```bash

        agentmail agent sign-up --human-email user@example.com --username my-agent

        ```'
      tags:
      - Agent
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_agent_AgentSignupResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__ValidationErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_agent_AgentSignupRequest'
  /v0/agent/verify:
    post:
      operationId: verify
      summary: Verify
      description: 'Verify an agent organization using the 6-digit OTP sent to the human''s email during sign-up.


        On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied.


        The OTP expires after 24 hours and allows a maximum of 10 attempts. If you run into any difficulties receiving the OTP code, you can also create an account on console.agentmail.to using the human email address you provided to verify your account.


        **CLI:**

        ```bash

        agentmail agent verify --otp-code 123456

        ```'
      tags:
      - Agent
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_agent_AgentVerifyResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_agent_AgentVerifyRequest'
components:
  schemas:
    type_agent_AgentSignupResponse:
      type: object
      properties:
        organization_id:
          type: string
          description: ID of the created organization.
        inbox_id:
          type: string
          description: ID of the auto-created inbox.
        api_key:
          type: string
          description: API key for authenticating subsequent requests. Store this securely, it cannot be retrieved again.
      required:
      - organization_id
      - inbox_id
      - api_key
      description: Response after successful agent sign-up.
      title: AgentSignupResponse
    type__ErrorCode:
      type: string
      description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
      title: ErrorCode
    type_agent_AgentVerifyResponse:
      type: object
      properties:
        verified:
          type: boolean
          description: Whether the organization was verified.
      required:
      - verified
      description: Response after successful agent verification.
      title: AgentVerifyResponse
    type__ErrorFix:
      type: string
      description: The concrete next action that resolves the error.
      title: ErrorFix
    type__ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_agent_AgentVerifyRequest:
      type: object
      properties:
        otp_code:
          type: string
          description: 6-digit verification code sent to the human's email address.
      required:
      - otp_code
      description: Request body to verify an agent with an OTP code.
      title: AgentVerifyRequest
    type__ErrorDocs:
      type: string
      description: Link to the error reference entry for this code.
      title: ErrorDocs
    type__ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type__ErrorName'
        code:
          $ref: '#/components/schemas/type__ErrorCode'
        message:
          $ref: '#/components/schemas/type__ErrorMessage'
        errors:
          description: Validation errors. Each entry has a path and a message identifying the invalid field.
        fix:
          $ref: '#/components/schemas/type__ErrorFix'
        docs:
          $ref: '#/components/schemas/type__ErrorDocs'
      required:
      - name
      - errors
      title: ValidationErrorResponse
    type_agent_AgentSignupRequest:
      type: object
      properties:
        human_email:
          type: string
          description: Email address of the human who owns the agent. A 6-digit OTP will be sent to this address.
        username:
          type: string
          description: Username for the auto-created inbox (e.g. "my-agent" creates my-agent@agentmail.to).
        source:
          type: string
          description: 'The SDK, framework, or platform issuing this sign-up (e.g. `agentmail-python`, `agentmail-cli`, `agentmail-mcp`).

            Identifies the caller — answers "who is signing up".

            Max 2048 characters.'
        referrer:
          type: string
          description: 'The channel that drove this sign-up — where the agent or its developer discovered AgentMail

            (e.g. `agent.email`, a partner URL, a campaign tag). Answers "where did this sign-up come from".

            Max 2048 characters.'
      required:
      - human_email
      - username
      description: Request body to sign up an agent.
      title: AgentSignupRequest
    type__ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer