gmail_log_search
Search one Gmail account's log metadata to trace message delivery, find Google notices by subject, or check bounce and throttle replies.
Instructions
Search ONE account's Gmail log (metadata only), one row per message.
The Admin console's "Email log search" for one account: which messages
reached or left the mailbox in a window, with their subject, Message-ID,
destinations and Google's delivery reply. Use it to find a notice Google
sent the account (filter by subject), to confirm one message's
delivery (message_id), or to see what Google answered when mail to or
from the account bounced or was throttled (responses). It never reads
a message body: it issues only Reports API activities().list for the
gmail application under userKey=<username>, on the same
admin.reports.audit.readonly DWD scope as user_activity. The
tenant must have Gmail log events in the Reports API.
The log does not carry the sender's address (its source is empty in
the API), so a sender is recognisable only by the domain on the right of
the Message-ID and by link_domains. Events are grouped by
rfc2822_message_id; per message: first / last event time,
events (deliveries etc. counted raw), event_names,
action_types (Google's numeric codes, undocumented, passed through),
destinations (as Google flattens them, channel::address),
spam (any event marked it), attachments, link_domains, and
responses -- the distinct non-empty description replies other
than the 250 accepted ones. Rows are newest last first, cut at
max_messages with truncated saying so.
Filters select messages, not events: a message is kept when any of its
events matches, and its row then aggregates all of its events (a
throttle reply that carries no subject stays on the row). subject and recipient
are case-insensitive substrings (of the subject / of the flattened
destinations), message_id is exact (angle brackets optional).
events_scanned counts events before filtering. capped means more
pages existed beyond max_pages (1000 events per page) -- the older
part of the window was not read, so "not found" does not hold. Today's
log can lag by hours.
Args:
username: Exact user email, passed through as the Reports API
userKey.
hours: Window length ending at end, 1..:data:GMAIL_LOG_MAX_HOURS
(the API refuses a gmail scan longer than 30 days).
end: End of the window, ISO 8601 with an offset
(2026-10-26T00:00:00+09:00). Default: now. Must not be in
the future.
subject: Keep messages whose subject contains this text.
message_id: Keep the message with this RFC 822 Message-ID.
recipient: Keep messages whose destinations contain this text
(an address or a domain).
max_pages: Page budget, 1..:data:GMAIL_LOG_MAX_PAGES.
max_messages: Rows returned, 1..:data:GMAIL_LOG_MAX_MESSAGES.
domain: Configured [domain.*] section to route the lookup
through. Default: resolved from the username's suffix.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"username": "<username>"
},
"name": "gmail_log_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| hours | No | ||
| domain | No | ||
| subject | No | ||
| username | Yes | ||
| max_pages | No | ||
| recipient | No | ||
| message_id | No | ||
| max_messages | No |