Deadsimple Email Auth API

openapi: 3.2.0
info:
  title: Dead Simple Email Auth API
  version: 0.1.0
  description: 'Email API for AI agents. Create inboxes, send and receive email,

    manage threads, and get real-time webhook notifications.


    ## Authentication

    All authenticated endpoints use Bearer token auth:

    ```

    Authorization: Bearer dse_your_api_key

    ```


    ## Agent self-signup

    Autonomous agents can provision an account, a key, and a live inbox in one

    unauthenticated call — no human, no verification email:

    ```

    POST /v1/auth/agent-signup

    ```

    That returns a `trial` account (1 inbox, 10 sends/hour, 25 sends/day) with a

    scoped key. `POST /v1/auth/claim` attaches a verified email and moves it to

    the Free plan, keeping the same key, inboxes and history.


    ## Sign in with Dead Simple (OpenID Connect)

    `https://id.deadsimple.email` is an OpenID Connect provider where the

    identity is an agent''s inbox: `sub` is the `inbox_id`, `email` is the inbox

    address. Discovery at `/.well-known/openid-configuration`, JWKS at

    `/.well-known/jwks.json`, ES256 id_tokens, authorization-code + PKCE S256,

    RFC 7591 registration at `/register`. Open clients (client_id = the app''s

    https origin) need no registration. An agent authenticates at `/authorize`

    with `Authorization: Bearer dse_...` plus `inbox_id=`, or with an ES256

    assertion signed by a key enrolled via `/v1/inboxes/{inbox_id}/identity/keys`;

    the one-call helper `POST /v1/inboxes/{inbox_id}/identity/sign-in` wraps

    this for SDKs and the MCP server. Endpoints on the `id.deadsimple.email`

    host are tagged **Identity Provider** below and carry their own `servers`

    entry.


    ## Pay per request (no API key)

    Twelve priced routes can be called with no credentials at all. They answer

    `402 Payment Required` carrying an x402 v2 `PAYMENT-REQUIRED` header (USDC

    on Base, Polygon or Solana, `exact` scheme, PayAI facilitator; the same

    JSON is repeated in the body for v1 clients) and, on `POST /v1/inboxes`,

    a `WWW-Authenticate: Payment` challenge for Stripe''s Machine Payments

    Protocol. Retry with `PAYMENT-SIGNATURE` (x402 v2), `X-PAYMENT` (v1) or

    `Authorization: Payment ` (MPP). x402 payments are verified

    before the work and settled after it; MPP charges first and refunds if

    the work fails. Prices: inbox $1.00, send/reply/reply-all/forward $0.01,

    reads $0.005. The paying wallet keys a `payg` account, and the first paid

    inbox returns `credentials` (an API key) in the response so later reads

    and sends within the plan are free. See the reusable `402` response and

    https://deadsimple.email/pay-per-request.html.


    ## Idempotency

    POST endpoints accept an `Idempotency-Key` header. Same key within 24h

    returns the cached response without re-executing.


    ## Rate Limits

    Every response includes rate limit headers:

    - `X-RateLimit-Limit` — requests per window

    - `X-RateLimit-Remaining` — remaining requests

    - `X-RateLimit-Reset` — window reset timestamp


    On `429`, a `Retry-After` header gives the seconds to wait. Per-account

    limits scale with plan (`rate_limit_rpm`); public/unauthenticated endpoints

    are additionally limited per IP.


    ## Webhook Reliability

    Every event is a durable delivery: the first attempt runs immediately and

    failures are retried on an exponential-backoff schedule (configurable per

    webhook via `/v1/webhooks/{id}/config`; default `[1, 30, 300, 1800, 7200,

    86400]` seconds). Deliveries are HMAC-SHA256 signed on **all plans**. The

    per-webhook delivery log (`/v1/webhooks/{id}/deliveries`) records every

    attempt with status and error, and any delivery can be replayed. Endpoints

    that fail repeatedly are auto-disabled.


    ## WebSocket Streaming

    Connect to `wss://ws.deadsimple.email?api_key=dse_...` for real-time events.


    After connecting, subscribe to specific inboxes/events:

    ```json

    {"action": "subscribe", "inbox_ids": ["..."], "events": ["message.received"]}

    ```


    Events are pushed as JSON with the same payload as webhooks. Send `{"action": "ping"}`

    to keep the connection alive (10-minute idle timeout).'
  contact:
    url: https://deadsimple.email
  license:
    name: MIT
servers:
- url: https://api.deadsimple.email
  description: Production
security:
- BearerAuth: []
tags:
- name: Auth
paths:
  /v1/auth/signup:
    post:
      summary: Create an account
      security: []
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                name:
                  type: string
                ref:
                  type: string
                  description: 'Optional affiliate referral code (from a `https://deadsimple.email/?via={code}` link). Invalid or unknown codes are ignored — they never fail signup.

                    '
            example:
              email: dev@example.com
              password: securepass123
              name: Alex
      responses:
        '201':
          description: Account created, verification email sent
        '400':
          description: Validation error
        '409':
          description: Email already registered
      operationId: postV1AuthSignup
      x-operation-id-source: derived
  /v1/auth/verify:
    post:
      summary: Verify email with code
      security: []
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              properties:
                email:
                  type: string
                code:
                  type: string
      responses:
        '201':
          description: Email verified, session token and API key returned
      operationId: postV1AuthVerify
      x-operation-id-source: derived
  /v1/auth/login:
    post:
      summary: Log in
      security: []
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        '201':
          description: Session token returned
        '401':
          description: Invalid credentials or unverified email
      operationId: postV1AuthLogin
      x-operation-id-source: derived
  /v1/auth/logout:
    post:
      summary: Revoke current session
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '201':
          description: Session revoked
      operationId: postV1AuthLogout
      x-operation-id-source: derived
  /v1/auth/forgot-password:
    post:
      summary: Request password reset code
      security: []
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
      responses:
        '201':
          description: Reset code sent (if email exists)
      operationId: postV1AuthForgotPassword
      x-operation-id-source: derived
  /v1/auth/reset-password:
    post:
      summary: Reset password with code
      security: []
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              - new_password
              properties:
                email:
                  type: string
                code:
                  type: string
                new_password:
                  type: string
                  minLength: 8
      responses:
        '201':
          description: Password updated
      operationId: postV1AuthResetPassword
      x-operation-id-source: derived
  /v1/auth/agent-signup:
    post:
      summary: Self-serve signup for autonomous agents
      security: []
      description: 'Provisions an account, an API key, and a live inbox in a single unauthenticated call, so an agent can get an email identity with no human in the loop. The ordinary signup flow needs a mailbox to receive a verification code, which a brand-new agent does not have.


        The resulting account is on the `trial` plan: 1 inbox, 10 sends/hour, 25 sends/day, no custom domains. The key it returns is scoped — it cannot buy domains, change billing, create further API keys, manage the team, or create workspaces.


        Signups are limited per client IP (3/hour, 10/day) and by a platform-wide hourly ceiling; when that ceiling is hit the endpoint returns `503 signup_capacity_reached`.


        Call `POST /v1/auth/claim` to attach a verified email and move to the Free plan, which lifts the trial send limits.'
      tags:
      - Auth
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 24
        description: 'Optional. Random, high-entropy value (a UUID works) that makes a retried signup return the original credentials instead of creating a second account. Treat it as a secret — for 24 hours it can retrieve this account''s API key. Values shorter than 24 characters are rejected.

          '
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  maxLength: 64
                  description: Optional name for the agent, used on the inbox and API key.
                ref:
                  type: string
                  description: 'Optional affiliate referral code. Invalid or unknown codes are ignored — they never fail signup.

                    '
            example:
              label: research-bot
      responses:
        '201':
          description: Account, API key, and inbox provisioned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: string
                  api_key:
                    type: string
                    description: 'Shown once. Send as `Authorization: Bearer <api_key>`.'
                  key_id:
                    type: string
                  inbox:
                    type: object
                    properties:
                      inbox_id:
                        type: string
                      email:
                        type: string
                  plan:
                    type: object
                  next_steps:
                    type: object
        '400':
          description: Idempotency-Key supplied but too short
        '429':
          description: Per-IP signup limit reached
        '503':
          description: Platform-wide signup capacity reached; retry shortly
      operationId: postV1AuthAgentSignup
      x-operation-id-source: derived
  /v1/auth/claim:
    post:
      summary: Start claiming an agent account with a real email
      description: Sends a verification code to `email`. Authenticated with the agent's own trial API key, so only the holder of that key can begin a claim.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
            example:
              email: operator@company.com
      responses:
        '201':
          description: Verification code sent
        '400':
          description: Invalid/disposable email, email already registered, or account already claimed
        '429':
          description: Too many claim attempts for this account
      operationId: postV1AuthClaim
      x-operation-id-source: derived
  /v1/auth/claim/verify:
    post:
      summary: Finish claiming an agent account (trial -> free)
      description: Confirms the code and upgrades the account to the Free plan. The account_id, API key, inboxes and message history are all preserved; only the owner identity and the plan change, and the trial send limits stop applying.
      tags:
      - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              properties:
                email:
                  type: string
                  format: email
                code:
                  type: string
                password:
                  type: string
                  minLength: 8
                  description: 'Optional dashboard password. If omitted, use POST /v1/auth/forgot-password to set one later.

                    '
            example:
              email: operator@company.com
              code: '123456'
      responses:
        '201':
          description: Account claimed and upgraded to Free
        '400':
          description: Invalid or expired code, or account already claimed
        '409':
          description: Email already registered to another account
      operationId: postV1AuthClaimVerify
      x-operation-id-source: derived
  /v1/auth/me:
    get:
      summary: Get current account info
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Account and user info
      operationId: getV1AuthMe
      x-operation-id-source: derived
components:
  parameters:
    WorkspaceHeader:
      name: X-Workspace-Id
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Target a specific workspace. Required for account-wide API keys that want workspace-scoped results.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key (dse_...), session token (JWT), or OAuth 2.1 access token (dse_oat_..., obtained via the authorization-code + PKCE flow below)
    OAuth2:
      type: oauth2
      description: OAuth 2.1 for MCP clients. Public clients only (PKCE S256 required, no client secret). Supports RFC 7591 dynamic client registration at /oauth/register and discovery via /.well-known/oauth-authorization-server. Access tokens carry inbox/message permissions only (no billing, team, or API-key administration).
      flows:
        authorizationCode:
          authorizationUrl: https://api.deadsimple.email/oauth/authorize
          tokenUrl: https://api.deadsimple.email/oauth/token
          refreshUrl: https://api.deadsimple.email/oauth/token
          scopes:
            email: Send, receive, and manage email inboxes
    OpenIDConnect:
      type: openIdConnect
      openIdConnectUrl: https://id.deadsimple.email/.well-known/openid-configuration
      description: 'Sign in with Dead Simple. Relying parties use this to authenticate an agent by its inbox; it is not used to call the Dead Simple API itself. Scopes: openid, email, profile (open clients); owner_email, org, offline_access (registered clients only).'