fabricatedemail-com MCP API

openapi: 3.2.0
info:
  title: fabricatedemail HTTP MCP API
  version: 1.0.0
  description: '## General contract


    - Every error response has body `{"error": ""}`. The message is

    human-facing and may change; branch on the status code, never on the

    string.

    - Checks run in the order authentication (`401`) → account state (`403`) →

    rate limit (`429`) → request validation (`400`) → existence and

    ownership (`404`) → cross-key conflict (`409`) → address cap (`429`).

    A request that is wrong in two ways gets the earlier status.

    - Unknown routes and methods are `404 {"error": "Not found"}`, including

    after successful authentication.

    - Every timestamp is exactly the format of JavaScript

    `Date.prototype.toISOString()`: millisecond precision, trailing `Z`.

    - Request bodies must be JSON objects. A malformed body, a JSON array or a

    bare JSON string is `400`. Unknown fields are ignored.

    - Register first, then trigger the mail. A `201` from `POST /subscriptions`

    means the mailbox is committed and visible to the mail handler, and a

    stored message is visible to your very next poll.'
servers:
- url: https://api.fabricatedemail.com
  description: Production.
security:
- apiKey: []
tags:
- name: MCP
  description: The same operations as tools for an MCP client.
paths:
  /mcp:
    post:
      operationId: mcp
      tags:
      - MCP
      summary: The Model Context Protocol endpoint
      description: 'Streamable HTTP transport. Authentication, the key rules and the rate

        limit are the same as the rest of the API: `Authorization: Bearer

        `.


        The tools are the operations of this document that carry an

        `x-mcp-tool` block, and their definitions are generated from it:

        `create_address`, `list_addresses`, `delete_address`,

        `wait_for_message`, `get_message` and `extract`. Each is a thin call to

        the handler behind the operation, so a tool''s failure modes are that

        operation''s statuses.


        The request and response bodies are JSON-RPC 2.0 messages as the

        Model Context Protocol defines them; this document does not restate

        that wire format.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: A JSON-RPC 2.0 request, notification or response, as MCP defines it.
      responses:
        '200':
          description: 'A JSON-RPC response, as `application/json` for a single reply or as

            `text/event-stream` when the transport streams.

            '
          content:
            application/json:
              schema:
                type: object
                description: A JSON-RPC 2.0 response, as MCP defines it.
            text/event-stream:
              schema:
                type: string
                description: Server-sent events carrying JSON-RPC messages.
        '202':
          description: 'The body was a notification or a response, which has no reply. No

            body is returned.

            '
        '400':
          description: The body is not valid JSON, or not a JSON-RPC message MCP accepts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcError'
              examples:
                parseError:
                  value:
                    jsonrpc: '2.0'
                    error:
                      code: -32700
                      message: 'Parse error: Invalid JSON-RPC message'
                    id: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountSuspended'
        '406':
          description: 'The `Accept` header does not name both `application/json` and

            `text/event-stream`, which the transport requires of every client.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcError'
        '415':
          description: The `Content-Type` is not `application/json`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Unauthorized:
      description: 'The key or token is missing, malformed, unknown or revoked, or the key

        has no account. All of these are indistinguishable from outside.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              $ref: '#/components/examples/errorUnauthorized'
    ServerError:
      description: A server-side failure, logged by the service with the real cause. Retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal:
              $ref: '#/components/examples/errorInternal'
    RateLimited:
      description: 'The key passed 600 requests in a minute. `Retry-After` says when to

        come back. A well-behaved 30-second poll loop costs about two requests

        a minute and never sees this.

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              $ref: '#/components/examples/errorRateLimited'
    AccountSuspended:
      description: 'The key''s account is suspended. Every key of the account sees this, on

        every key route, from the next request on; a long poll already in

        flight is not interrupted, and the request after it gets this within

        30 seconds. Mail addressed to the account''s

        addresses is dropped meanwhile. Reinstatement makes the account work

        again; mail that arrived during the suspension is gone, and addresses

        and mail that expired meanwhile were deleted as usual.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            suspended:
              $ref: '#/components/examples/errorAccountSuspended'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-facing, and free to change. Branch on the status code.
    JsonRpcError:
      type: object
      description: 'A JSON-RPC 2.0 error, as the MCP transport writes it. `POST /mcp` is

        the one route whose failures do not use the API''s `{"error": "…"}`

        shape — except for the statuses the router decides before the transport

        sees the request, which do.

        '
      required:
      - jsonrpc
      - error
      - id
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: integer
            message:
              type: string
        id:
          type:
          - string
          - integer
          - 'null'
  examples:
    errorRateLimited:
      summary: 'The rate limit — sent with `Retry-After: 60`.'
      value:
        error: rate limited
    errorUnauthorized:
      value:
        error: unauthorized
    errorAccountSuspended:
      value:
        error: account suspended
    errorInternal:
      value:
        error: internal error
  headers:
    RetryAfter:
      description: 'Seconds to wait before retrying. Present on the rate-limit `429` and

        absent on the address-cap `429`, which is what tells the two apart

        without reading the message.

        '
      required: false
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'The 64-hex-character API key, created in the customer dashboard and

        shown once. The scheme is matched case-insensitively. A missing header,

        a malformed credential, an unknown key and a revoked key are all `401`

        and indistinguishable from outside.

        '
x-reserved-local-parts:
- abuse
- postmaster
- security
- support
- admin
- noreply
- no-reply
- hostmaster
- webmaster
- info
- billing
- legal
- dmarc