gmail_user_usage
Retrieve daily Gmail send, receive, exchange, and spam counts for one account to investigate suspected spam bursts or account compromise.
Instructions
Daily Gmail send/receive counts for ONE account (Admin SDK userUsageReport).
Answers "did this account send a burst of mail on day X" -- the question
after Google restricts an account for suspected spamming, or after a
compromise. gmail_usage_report is the domain-wide total and cannot
single one account out; this is the per-account counter.
Per day (newest first): num_emails_sent, num_emails_received,
num_emails_exchanged and num_spam_emails_received. totals
sums the days that returned a report; a counter that one of those days
lacks has a None total (unknown), never a partial sum, and when no
day reported at all every total is None. A day Google has no report
for (not processed yet -- these counters lag by days, and Google answers
such a day with a "not yet available" 400 -- or before the account
existed) is listed in missing_dates, never counted as zero.
A day Google answered with PARTIAL_DATA_AVAILABLE carries
partial: true and is listed in partial_dates; while that list is
non-empty the totals are lower bounds. A single day's fetch failing lands in date_errors; the other
days still answer. A missing DWD scope or a
rejected credential is a whole-call {"error": ...}.
Dates are the Reports API's own UTC-08:00 days (Pacific Standard Time, no DST): one such day runs 17:00 to 17:00 the next day in JST (UTC+09:00).
Read-only: only userUsageReport().get() is issued, on the same
admin.reports.usage.readonly DWD scope gmail_usage_report uses, so
a tenant already running that tool needs no additional grant.
Args:
username: Exact user email, passed through as the Reports API
userKey.
days: How many days to report, ending at end_date.
1..:data:MAX_USAGE_REPORT_DAYS.
end_date: Last day of the window, yyyy-mm-dd in UTC-08:00.
Default: yesterday there. Must not be later than that.
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_user_usage"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| domain | No | ||
| end_date | No | ||
| username | Yes |