MessageView

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/e2a-dev/json-schema/e2a-dev-message-view-schema.json",
  "title": "MessageView",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/e2a-dev-api-openapi.yml#/components/schemas/MessageView",
  "additionalProperties": true,
  "properties": {
    "attachments": {
      "items": {
        "$ref": "#/$defs/AttachmentMetaView"
      },
      "type": "array"
    },
    "authentication": {
      "anyOf": [
        {
          "$ref": "#/$defs/Authentication"
        },
        {
          "maxProperties": 0,
          "minProperties": 1,
          "type": [
            "object",
            "null"
          ]
        }
      ],
      "description": "Inbound SMTP authentication evidence. Only dmarc.status=pass authenticates the RFC 5322 From domain; even a pass does not authenticate the mailbox local part, a person, or message content. Null means there was no authenticating inbound SMTP peer, as with outbound or providerless loopback delivery."
    },
    "body": {
      "$ref": "#/$defs/MessageBodyView"
    },
    "cc": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "conversation_id": {
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "type": "string"
    },
    "deleted_at": {
      "description": "When the message was moved to the trash. Omitted for live messages. A trashed message is restorable until purged — 30 days after deletion by default (deployment-configurable). Live message data is otherwise retained indefinitely.",
      "format": "date-time",
      "type": "string"
    },
    "delivered_to": {
      "description": "The envelope Delivered-To address — this delivery's per-agent target (the mailbox that actually received this row), distinct from the To header (the to array).",
      "type": "string"
    },
    "delivery_detail": {
      "type": "string"
    },
    "delivery_status": {
      "description": "Outbound delivery rollup (worst recipient status by precedence; outbound only). Open set; tolerate unknown values. Known values: accepted, sending, sent, delivered, deferred, bounced, complained, failed. Lifecycle: accepted → sending → sent → delivered | deferred | bounced | complained | failed. While a future scheduled_at is pending, delivery_status remains accepted; scheduled is the SendResultView.status presentation value, not a delivery_status. (Legacy 'queued' is superseded by 'accepted'.)",
      "type": "string"
    },
    "direction": {
      "enum": [
        "inbound",
        "outbound"
      ],
      "type": "string"
    },
    "envelope_from": {
      "description": "SMTP MAIL FROM address for inbound SMTP delivery; null for outbound messages, a null reverse path, or providerless delivery.",
      "type": [
        "string",
        "null"
      ]
    },
    "flag_reason": {
      "type": "string",
      "x-stability-level": "beta"
    },
    "flagged": {
      "type": "boolean",
      "x-stability-level": "beta"
    },
    "header_from": {
      "description": "Parsed RFC 5322 From address for inbound mail or the sender identity for outbound mail; null when unavailable and never replaced by Reply-To.",
      "type": [
        "string",
        "null"
      ]
    },
    "hold_reason": {
      "$ref": "#/$defs/HoldReasonView",
      "x-stability-level": "beta"
    },
    "id": {
      "type": "string"
    },
    "labels": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "parsed": {
      "$ref": "#/$defs/MessageParsedView"
    },
    "protection": {
      "description": "Screening breakdown behind the hold — detector categories + rationale (review surface only, beta).",
      "items": {
        "$ref": "#/$defs/ProtectionFindingView"
      },
      "type": [
        "array",
        "null"
      ],
      "x-stability-level": "beta"
    },
    "raw_message": {
      "contentEncoding": "base64",
      "description": "Base64-encoded canonical RAW MIME. Required but null while an outbound message is pending review because reviewer-editable content lives in body until approval composes the final MIME; non-null for inbound and composed outbound messages.",
      "type": [
        "string",
        "null"
      ]
    },
    "read_status": {
      "type": "string"
    },
    "reply_to": {
      "description": "The parsed Reply-To header of an inbound message. Populated for inbound only; always empty for outbound (a Reply-To you SET on a send is a request-side field on the send/reply/forward body and is not echoed back here).",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "review_status": {
      "description": "Review-hold lifecycle (outbound only). Open set; tolerate unknown values. Known values: pending_review, sent, review_rejected, review_expired_approved, review_expired_rejected. Note: an APPROVED outbound hold reads as sent here — the message view intentionally collapses the approved outcome into the delivery lifecycle. The distinct review_approved spelling appears only in the approve result (SendResultView.status, for inbound release) and the email.review_approved webhook event, not in this field.",
      "type": "string"
    },
    "scheduled_at": {
      "description": "Beta: scheduled sending may change before it is declared stable. Future instant a scheduled outbound send was queued to be submitted (outbound only; treat as \"not before\"). Set when the message was created with a future send_at and retained afterwards; omitted for immediate sends. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before scheduled_at re-arms it; restoring at or after scheduled_at returns it live with delivery_status=failed and leaves the send canceled.",
      "format": "date-time",
      "type": "string",
      "x-stability-level": "beta"
    },
    "sent_as": {
      "description": "From identity used at relay accept time (outbound only). Open set; tolerate unknown values. Known values: own_address, relay.",
      "type": "string"
    },
    "size_bytes": {
      "description": "RAW MIME byte length of the whole stored message (headers + bodies + encoded attachments as transported). Distinct from attachments[].size_bytes, which is one attachment's DECODED payload size. This value is the dominant term of the account's storage-quota accounting (usage.storage_bytes).",
      "format": "int64",
      "type": "integer"
    },
    "subject": {
      "type": "string"
    },
    "thread_id": {
      "description": "Beta: server-owned email thread identity. This field may evolve or be removed before it is declared stable. Omitted when no thread has been assigned.",
      "type": "string",
      "x-stability-level": "beta"
    },
    "to": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "verified_domain": {
      "description": "RFC 5322 Author Domain validated by an aligned DMARC pass. Null for non-pass verdicts and deliveries without inbound SMTP evaluation — this includes dmarc.status=none (sender publishes no DMARC record, common and NOT itself suspicious) as well as dmarc.status=fail (an actual mismatch). Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not. This authenticates the domain, not the address local part, individual sender, or message content.",
      "type": [
        "string",
        "null"
      ]
    },
    "webhook_error": {
      "type": "string"
    },
    "webhook_status": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "header_from",
    "envelope_from",
    "verified_domain",
    "authentication",
    "to",
    "cc",
    "reply_to",
    "delivered_to",
    "subject",
    "conversation_id",
    "direction",
    "read_status",
    "labels",
    "created_at",
    "raw_message",
    "attachments"
  ],
  "type": "object",
  "$defs": {
    "AttachmentMetaView": {
      "additionalProperties": true,
      "properties": {
        "content_id": {
          "description": "Content-ID (angle brackets stripped) for an inline part referenced by a body 'cid:' URL, e.g. an embedded image; the key a cid: reference resolves against. Omitted for non-inline attachments.",
          "type": "string"
        },
        "content_type": {
          "type": "string"
        },
        "filename": {
          "type": "string"
        },
        "index": {
          "description": "Stable 0-based attachment index (document order) — the fetch key for the attachment-bytes endpoint.",
          "format": "int64",
          "type": "integer"
        },
        "size_bytes": {
          "description": "DECODED attachment payload size in bytes (Content-Transfer-Encoding undone) — the size of the file a download yields, not its encoded size inside the raw MIME.",
          "format": "int64",
          "type": "integer"
        }
      },
      "required": [
        "size_bytes",
        "index"
      ],
      "type": "object"
    },
    "Authentication": {
      "additionalProperties": true,
      "properties": {
        "dkim": {
          "description": "One result per DKIM signature, in message header order. An unsigned message carries an empty array.",
          "items": {
            "$ref": "#/$defs/DKIMResult"
          },
          "type": "array"
        },
        "dmarc": {
          "$ref": "#/$defs/DMARCResult",
          "description": "DMARC evaluation of the RFC 5322 Author Domain against aligned SPF and DKIM evidence."
        },
        "spf": {
          "$ref": "#/$defs/SPFResult",
          "description": "SPF evidence for the SMTP peer and RFC 5321 identity."
        }
      },
      "required": [
        "spf",
        "dkim",
        "dmarc"
      ],
      "type": "object"
    },
    "DKIMResult": {
      "additionalProperties": true,
      "properties": {
        "aligned": {
          "description": "Whether a passing DKIM signing domain aligns with the RFC 5322 Author Domain under the discovered DMARC policy; null unless status is pass and an applicable DMARC record was discovered.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "detail": {
          "description": "Free-text diagnostic for humans and logs. Never parse or branch on this field.",
          "type": "string"
        },
        "domain": {
          "description": "DKIM signing domain from the signature d= tag; null when it could not be parsed.",
          "type": [
            "string",
            "null"
          ]
        },
        "selector": {
          "description": "DKIM selector from the signature s= tag; null when it could not be parsed.",
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "description": "Result for this DKIM signature. policy means e2a deliberately refused the signature, such as one using the unsafe l= body-length tag.",
          "enum": [
            "pass",
            "fail",
            "none",
            "neutral",
            "policy",
            "temperror",
            "permerror"
          ],
          "type": "string"
        }
      },
      "required": [
        "status",
        "domain",
        "selector",
        "aligned"
      ],
      "type": "object"
    },
    "DMARCResult": {
      "additionalProperties": true,
      "properties": {
        "aligned_by": {
          "description": "Mechanisms that both passed and aligned. Empty unless status is pass; each mechanism appears at most once.",
          "items": {
            "enum": [
              "spf",
              "dkim"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "detail": {
          "description": "Free-text diagnostic for humans and logs. Never parse or branch on this field.",
          "type": "string"
        },
        "domain": {
          "description": "RFC 5322 Author Domain evaluated by DMARC; null when no single valid Author Domain exists.",
          "type": [
            "string",
            "null"
          ]
        },
        "policy": {
          "description": "Effective policy requested by the applicable DMARC record. This is sender-published metadata, not an action e2a took and not authentication strength.",
          "enum": [
            "none",
            "quarantine",
            "reject"
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "description": "DMARC verdict. Only pass authenticates domain-authorized use of the RFC 5322 Author Domain. none means the sender publishes no DMARC record (common, not itself suspicious) and is distinct from fail, an actual alignment mismatch.",
          "enum": [
            "pass",
            "fail",
            "none",
            "temperror",
            "permerror"
          ],
          "type": "string"
        }
      },
      "required": [
        "status",
        "domain",
        "policy",
        "aligned_by"
      ],
      "type": "object"
    },
    "HoldReasonView": {
      "additionalProperties": true,
      "properties": {
        "category": {
          "description": "Top screening category when a scan hold has detail enrichment.",
          "type": "string"
        },
        "code": {
          "description": "Stable machine-readable hold code. Open set; tolerate unknown values.",
          "type": "string"
        },
        "confidence": {
          "description": "Screening confidence from 0 through 1 when available. Intended for expanded technical detail, not the queue summary.",
          "format": "double",
          "type": "number"
        },
        "detail": {
          "description": "Validated plain-language detector rationale when available.",
          "type": "string"
        },
        "summary": {
          "description": "Plain-language explanation suitable for showing directly to a reviewer.",
          "type": "string"
        },
        "type": {
          "description": "Producer that caused the hold. Open set; tolerate unknown values. Known values: gate, scan, send, unknown.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "summary"
      ],
      "type": "object",
      "x-stability-level": "beta"
    },
    "MessageBodyView": {
      "additionalProperties": true,
      "properties": {
        "html": {
          "type": "string"
        },
        "text": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "MessageParsedView": {
      "additionalProperties": true,
      "properties": {
        "html": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "truncated": {
          "type": "boolean"
        }
      },
      "required": [
        "text",
        "truncated"
      ],
      "type": "object"
    },
    "ProtectionFindingView": {
      "additionalProperties": true,
      "properties": {
        "action": {
          "description": "Applied action for this finding. Open set. Known values: flag, review, block.",
          "type": "string"
        },
        "categories": {
          "description": "Detected threat categories, highest-confidence first (scan findings only).",
          "items": {
            "$ref": "#/$defs/ThreatCategoryView"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "detector": {
          "description": "Content-scan detector(s) that contributed (scan findings only), e.g. \"gemini\".",
          "type": "string"
        },
        "score": {
          "description": "Aggregate content-scan score 0..1 (scan findings only).",
          "format": "double",
          "type": "number"
        },
        "source": {
          "description": "Which producer flagged the message. Open set; tolerate unknown values. Known values: gate, scan.",
          "type": "string"
        },
        "summary": {
          "description": "Short natural-language rationale for a scan finding (curated; never the raw provider payload).",
          "type": "string"
        }
      },
      "required": [
        "source"
      ],
      "type": "object",
      "x-stability-level": "beta"
    },
    "SPFResult": {
      "additionalProperties": true,
      "properties": {
        "aligned": {
          "description": "Whether a passing SPF identity aligns with the RFC 5322 Author Domain under the discovered DMARC policy; null unless status is pass and an applicable DMARC record was discovered.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "detail": {
          "description": "Free-text diagnostic for humans and logs. Never parse or branch on this field.",
          "type": "string"
        },
        "domain": {
          "description": "RFC 5321 identity domain evaluated by SPF; null when no SPF identity was available.",
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "description": "SPF evaluation result. Only pass can contribute to DMARC alignment.",
          "enum": [
            "pass",
            "fail",
            "none",
            "neutral",
            "softfail",
            "temperror",
            "permerror"
          ],
          "type": "string"
        }
      },
      "required": [
        "status",
        "domain",
        "aligned"
      ],
      "type": "object"
    },
    "ThreatCategoryView": {
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string"
        },
        "score": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "name"
      ],
      "type": "object",
      "x-stability-level": "beta"
    }
  }
}