gmail_message_trace
Check whether a message (by RFC 822 Message-ID) reached specific users' mailboxes.
Instructions
Check whether a message (by RFC 822 Message-ID) reached specific users' mailboxes.
Answers "who got this email and who didn't" for a KNOWN Message-ID and a KNOWN candidate recipient list — there is no Workspace API to search across every user for one message, so the caller supplies who to check (a mailing-list roster, or simply the people who reported a problem). For each recipient this impersonates that exact user via domain-wide delegation and searches their own mailbox (including Spam and Trash) for the Message-ID.
Requires the gmail.readonly DWD scope — granted PER SERVICE ACCOUNT
CLIENT ID in the Admin console (Security > API controls > Domain-wide
delegation), separately from the admin.directory.* / admin.reports.*
scopes the rest of this server uses, and NOT on by default. A domain
missing that grant reports a per-recipient error rather than a
silent "not found" — the two must never be confused, since "not found"
here can also legitimately mean the message was delivered and later
deleted by the user, or never delivered at all; this tool cannot tell
those apart, only "a match currently exists in this mailbox" from "it
doesn't".
Read-only: only messages().list and messages().get (metadata
only, never the message body) are issued against each impersonated
mailbox — see DomainClient.find_message_by_id.
A per-recipient result sets ambiguous: true (with match_count)
when more than one message in that mailbox shares the Message-ID (e.g. a
mailing-list copy plus a direct CC) — the other fields describe only the
first match in that case, not a combined answer. match_count_capped
is set alongside it when the mailbox has enough matches that
match_count itself is a lower bound, not exact.
Args:
message_id: The RFC 822 Message-ID to search for, with or without
angle brackets. Must be shaped like an address (local@domain,
no whitespace) — this is validated before use, since it is
interpolated into a Gmail search query.
recipients: Comma- and/or whitespace-separated exact recipient email
addresses to check (max 50 per call — split a larger list across
multiple calls rather than expecting a partial result).
domain: Configured [domain.*] section to route EVERY recipient
through. Default: resolved per-recipient from their own address
suffix, so one call can cover a mixed staff/student list. Set
this only when recipients use an alias/secondary domain with no
config section of its own.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| message_id | Yes | ||
| recipients | Yes |