Skip to Content

The MessageMeta type of the TypeScript SDK, which labels.listMessages and 5 more methods take or answer.

type MessageMeta = {
  auth: MessageAuth
  bcc: ContentAddress[] | null
  blobGen: string
  blobHash: string
  cc: ContentAddress[] | null
  deliveryMeta: Record<string, unknown> | null
  deliveryState: ('queued' | 'relayed' | 'delivered' | 'failed' | 'mixed') | null
  envelopeFrom: string
  envelopeTo: string
  flags: string[]
  from: ContentAddress[] | null
  hasAttachment: boolean | null
  id: string
  inReplyTo: string | null
  keywords: string[]
  labels: MessageLabel[]
  messageIdHeader: string | null
  modseq?: number
  receivedAt: number
  referencesIds: string[]
  restoresTo?: string[] | null
  sentAt: number | null
  size: number
  snippet: string | null
  subject: string | null
  threadId: string | null
  to: ContentAddress[] | null
  uid?: number
}

Fields

FieldTypeDescription
authMessageAuth
bccContentAddress[] | nullParsed Bcc header addresses for composed drafts, or null
blobGenstringStorage generation identifier
blobHashstringSHA-256 hash of raw MIME content in storage
ccContentAddress[] | nullParsed Cc header addresses, or null if unparseable
deliveryMetaRecord<string, unknown> | nullInbound delivery audit metadata
deliveryState('queued' | 'relayed' | 'delivered' | 'failed' | 'mixed') | nullWhat became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery.
envelopeFromstringSMTP envelope sender address
envelopeTostringSMTP envelope recipient address
flagsstring[]System flags (seen, answered, flagged, draft, deleted)
fromContentAddress[] | nullParsed From header addresses, or null if unparseable
hasAttachmentboolean | nullTrue if message has file attachments, null if not yet determined
idstringUnique message identifier (ULID)
inReplyTostring | nullIn-Reply-To header Message-ID, or null
keywordsstring[]Custom JMAP keywords (e.g. $forwarded)
labelsMessageLabel[]Labels attached to this message with per-label UIDs
messageIdHeaderstring | nullMessage-ID header value, or null
modseqnumberOptional. Per-label MODSEQ (present in label UID listings)
receivedAtnumberTimestamp when message was received by server in epoch seconds
referencesIdsstring[]List of Message-IDs from References header
restoresTostring[] | nullOptional. Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.
sentAtnumber | nullSent timestamp from Date header in epoch seconds, or null
sizenumberTotal message size in bytes
snippetstring | nullShort plain-text preview of message body
subjectstring | nullMessage subject line, or null
threadIdstring | nullConversation thread identifier (ULID), or null
toContentAddress[] | nullParsed To header addresses, or null if unparseable
uidnumberOptional. Per-label UID (present in label UID listings)

Used by

MethodWhat it does
labels.listMessagesList messages in a label by UID
messages.listList mailbox messages
messages.getGet message metadata
search.fullTextFull-text search a mailbox
search.semanticSemantic (meaning-based) search of a mailbox
threads.getGet a conversation thread

Used in

BatchRestoreEntry, BatchUnjunkEntry, BatchUntrashEntry, BatchUpdateEntry, EmailSearchResult, ExpungedMessageMeta, MessageBatch, MessageRestoreResult, SemanticSearchResult, SimilarMessagesResult, ThreadListItem, ThreadView.