---
title: List received emails
openapi: /openapi/mailfully.yaml GET /v1/emails/receiving
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`GET https://api.mailfully.com/v1/emails/receiving`

List the organization's received email, newest first. Rows carry metadata only; fetch one email for its body.

Paging runs both ways. Pass a response's `next_cursor` as `after` for the next, older page, or its `prev_cursor` as `before` to walk back toward newer mail. `after` and `before` cannot be combined. Every page is newest first whichever way it was reached, and `has_more` says whether another page lies in the direction you are moving.

Received mail has no test or live split: a `mf_test_` key reads the same mail as a `mf_live_` key. Rows older than the plan's retention window are never returned. Requires the `read:inbound` scope; `send` and `read:emails` do not grant it.

## Authentication

- `apiKey` — http bearer

## Query parameters

- `limit` (integer) — Maximum rows to return. Default 25, clamped to [1, 100].
- `after` (string) — A previous response's `next_cursor`. Continues to older mail.
- `before` (string) — A previous response's `prev_cursor`. Walks back to newer mail.
- `q` (string) — Text (1-200 characters) matched as a substring of the subject, the sender address, or the sender's display name.
- `domain` (string) — Only mail sent to an address at this domain (matched against `received_for`).
- `has_attachments` (string) — Only mail with at least one attachment. Accepts `true` only.
- `spam` (string) — Only mail whose `spam` verdict is `FAIL`. Accepts `true` only.

## Response 200

A page of received emails.
  - response (object)
    - `data` (array, required)
      - `items` (object)
        - `id` (string, required) — The received email id (`inb_…`).
        - `created_at` (string, date-time, required) — When Mailfully received the email.
        - `from` (string, required) — The sender's bare address.
        - `from_header` (string, required) — The `From` header as written, display name included. Empty when absent.
        - `to` (array, required) — Addresses in the `To` header.
          - `items` (string)
        - `cc` (array, required) — Addresses in the `Cc` header.
          - `items` (string)
        - `received_for` (array, required) — The envelope recipients at this organization's domains, lowercased. Includes blind-copied recipients and never lists another organization's addresses.
          - `items` (string)
        - `subject` (string, required) — The subject, or an empty string when there is none.
        - `message_id` (string, required) — The `Message-ID` header, or `null` when the sender set none.
        - `attachment_count` (integer, required)
        - `spam` (string, required, one of: PASS, FAIL, GRAY, PROCESSING_FAILED, null) — An SES verdict. `GRAY` means SES had nothing to check or could not decide; `null` means SES reported no verdict.
        - `virus` (string, required, one of: PASS, FAIL, GRAY, PROCESSING_FAILED, null) — An SES verdict. `GRAY` means SES had nothing to check or could not decide; `null` means SES reported no verdict.
        - `quota_locked` (boolean, required) — `true` while the email is locked because it arrived over the monthly ceiling or spend cap and usage is still over. Its content endpoints return `403 email_above_quota` until then.
    - `has_more` (boolean, required) — Whether another page lies in the direction of travel.
    - `next_cursor` (string, required) — Pass as `after` for older mail; `null` when there is none.
    - `prev_cursor` (string, required) — Pass as `before` for newer mail; `null` on the newest page.

## Response 401

Authentication failed.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 403

The credential is valid but not permitted.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 422

The request failed validation.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 500

An unexpected error occurred.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://mailfully.com/docs/api-specs.zip