Build around your inbox.

Get a mailbox token

Exchange an email address (or mailbox_id from its reading URL) and website password for a read-only Bearer token. The token expires after one hour. Password changes invalidate existing tokens.

{
  "access_token": "YOUR_MAILBOX_TOKEN",
  "expires_in": 3600,
  "mailbox": {
    "email": "you@example.com",
    "id": "11111111-1111-4111-8111-111111111111"
  },
  "scope": "mail:read",
  "token_type": "Bearer"
}

No cookies or CSRF token are needed for /api/v1. POST requests require application/json. Never put passwords or tokens in a URL.

Identify the authorized mailbox

Returns only the mailbox authorized by the token. There is no endpoint that lists other users’ mailboxes.

{
  "data": {
    "email": "you@example.com",
    "id": "11111111-1111-4111-8111-111111111111"
  }
}

List recent mail

Newest-first summaries from the latest 30 provider search candidates, after exact-recipient filtering. This is a recent-mail window, not a complete mailbox export.

{
  "data": [
    {
      "address": "hello@example.com",
      "code": "123456",
      "date": "2026-10-23T10:00:00+00:00",
      "epoch": "100",
      "from": "Example \u003chello@example.com\u003e",
      "sender": "Example",
      "snippet": "Your verification code is 123456.",
      "subject": "Your verification code",
      "uid": "42"
    }
  ],
  "meta": {
    "cached": false,
    "fetched_at": "2026-10-23T10:00:00+00:00",
    "has_more": false,
    "returned": 1,
    "window": 30
  }
}

Filters apply within the 30-message window. has_more means upstream search returned over 30 candidates; it does not expose a pagination cursor. Message data is cached in RAM for up to five seconds.

Read a message

Returns normalized text, safe structured blocks, visible HTTP(S) links and an image-blocking count. The UID and epoch must come from this mailbox’s message list.

{
  "data": {
    "address": "hello@example.com",
    "blocks": [
      {
        "runs": [
          {
            "text": "Your verification code is 123456."
          }
        ],
        "type": "paragraph"
      }
    ],
    "code": "123456",
    "date": "2026-10-23T10:00:00+00:00",
    "epoch": "100",
    "from": "Example \u003chello@example.com\u003e",
    "images_blocked": 1,
    "links": [],
    "sender": "Example",
    "snippet": "Your verification code is 123456.",
    "subject": "Your verification code",
    "text": "Your verification code is 123456.",
    "truncated": false,
    "uid": "42"
  }
}

Images, scripts, attachments and original sender HTML are never returned for rendering. IMAP reads the first 1 MiB of MIME. Gmail transfers at most 4 MiB of JSON and decodes up to 1 MiB of text, falling back to a snippet when oversized. Previews are limited to 200,000 characters/2,000 blocks; truncated=true indicates a bounded preview. Opened content is cached in RAM for up to two minutes.

Get the newest matching message

Returns the newest summary, or {"data":null} with HTTP 200 when nothing matches.

{
  "data": {
    "address": "hello@example.com",
    "code": "123456",
    "date": "2026-10-23T10:00:00+00:00",
    "epoch": "100",
    "from": "Example \u003chello@example.com\u003e",
    "sender": "Example",
    "snippet": "Your verification code is 123456.",
    "subject": "Your verification code",
    "uid": "42"
  }
}

Extract a recent email code

Finds the newest detected numeric verification code among the recent summaries, fetching up to five message bodies when snippets do not contain a code. Detection is heuristic, not proof of authenticity.

{
  "data": {
    "code": "123456",
    "date": "2026-10-23T10:00:00+00:00",
    "epoch": "100",
    "uid": "42"
  }
}

JSON returns data:null with HTTP 200 when no code is detected. format=text returns just the code (200), or an empty response (204). This reads codes from mail; it does not generate TOTP codes from a 2FA secret.

Read links from the latest email

Reads the newest matching message body and returns visible, deduplicated HTTP(S) links without visiting them.

{
  "data": {
    "links": [
      {
        "label": "Continue verification",
        "url": "https://example.com/verify?token=demo"
      }
    ],
    "uid": "42"
  }
}

No matching mail returns {"data":{"uid":null,"links":[]}} with HTTP 200.

Read multiple authorized mailboxes

Read up to ten mailboxes in one request. Every mailbox must have its own valid token; a token cannot authorize another mailbox. Results preserve input order, with per-item errors.

{
  "results": [
    {
      "data": [
        {
          "address": "hello@example.com",
          "code": "123456",
          "date": "2026-10-23T10:00:00+00:00",
          "epoch": "100",
          "from": "Example \u003chello@example.com\u003e",
          "sender": "Example",
          "snippet": "Your verification code is 123456.",
          "subject": "Your verification code",
          "uid": "42"
        }
      ],
      "index": 0,
      "mailbox": {
        "email": "you@example.com",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "meta": {
        "cached": false,
        "fetched_at": "2026-10-23T10:00:00+00:00"
      }
    },
    {
      "error": {
        "code": "invalid_token",
        "message": "A valid mailbox Bearer token is required."
      },
      "index": 1
    }
  ]
}

HTTP 200 can contain successful and failed items. Each token consumes one read from its quota. A batch consumes ten IP request credits. All tokens and credentials stay out of URLs.

Check application health

Checks the web process, not upstream mail-provider connectivity. It does not reveal configuration or mailbox counts.

{
  "api_version": "1",
  "status": "ok"
}