---
title: Retrieve a received email
openapi: /openapi/mailfully.yaml GET /v1/emails/receiving/{id}
---

> **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/{id}`

Retrieve one received email with its body, headers, SES verdicts, attachment metadata, and a download link for the original MIME.

By default (`html_format=data_uri`) every `cid:` image link in `html` that matches a stored attachment is replaced with a `data:` URI, up to 5 MB of images in total; past that, or with no match, the `cid:` link is left as is. `html_format=cid` returns the original links.

An email whose `virus` verdict is `FAIL` returns metadata only: `html`, `text`, and `raw` are `null` and `headers` is empty. An email that arrived over the plan's monthly ceiling or spend cap returns `403 email_above_quota` until the organization's usage is back within both. An unknown id, another organization's id, and an email past the retention window all return the same `404`. Requires the `read:inbound` scope.

## Authentication

- `apiKey` — http bearer

## Path parameters

- `id` (string, required) — The received email id (`inb_` followed by a 26-character ULID).

## Query parameters

- `html_format` (string) — How `cid:` image links in `html` are returned.

## Response 200

The received email.
  - response
    - (allOf)
      - value (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.
      - value (object)
        - `reply_to` (array, required)
          - `items` (string)
        - `in_reply_to` (string, required)
        - `references` (array, required)
          - `items` (string)
        - `size_bytes` (integer, required) — The size of the message as received.
        - `html` (string, required) — The HTML body. See `html_format` for how `cid:` images are returned.
        - `text` (string, required)
        - `headers` (array, required) — Every header in the order it appeared. Empty for a virus-flagged email.
          - `items` (object)
            - name: … (nested further)
            - value: … (nested further)
        - `authentication` (object, required)
          - `spf` (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.
          - `dkim` (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.
          - `dmarc` (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.
        - `attachments` (array, required) — Attachment metadata, without download links.
          - `items` (object)
            - id: … (nested further)
            - filename: … (nested further)
            - content_type: … (nested further)
            - content_disposition: … (nested further)
            - content_id: … (nested further)
            - size: … (nested further)
        - `raw` (object, required) — A link to the original `.eml` file. `null` when the email's `virus` verdict is `FAIL`.
          - `download_url` (string, required)
          - `expires_at` (string, date-time, required) — When `download_url` stops working, at most one hour after the request.

## 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 lacks the scope, or the email is locked over quota.
  - 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 404

The requested resource was not found.
  - 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