Get gmail activity logs from Google Workspace.

Syntax

Options

profile=PROFILE

Optional. Profile name of Google Workspace. If omitted, all Google Workspace connect profiles are queried.

user=USER

Optional. Email address or user ID. All users by default.

duration=NUM{mon|w|d|h|m|s}

Optional. Scan only recent data. You should use s(second), m(minute), h(hour), d(day), mon(month) time unit. For example, 10s means data from 10 seconds earlier. Up to 30 days. Cannot be used with the from or to option.

from=yyyyMMddHHmmss

Optional. Start time of range. yyyyMMddHHmmss format. If you omit time part, it will be padded by zero. Must be within the last 180 days.

to=yyyyMMddHHmmss

Optional. End time of range. yyyyMMddHHmmss format. If you omit time part, it will be padded by zero. Defaults to the current time.

raw=RAW

Optional. t or f. Specify 't' to output line field.

Output Fields

Error Codes

Parsing Errors

Description

Queries Gmail log events through the Google Reports API. Gmail logs may not be available depending on your Google Workspace edition. For the required permissions, see 1. Required Permissions in the install guide.

Due to Google API limits, the query range is restricted as follows.

• You must specify either the from or duration option.
• You can query up to 30 days at a time. Split longer periods into ranges of 30 days or less.
• Google keeps Gmail logs for 180 days, so from must be within the last 180 days.

A single mail produces several events. For example, when a mail is sent within the organization, SEND_INITIATED, UNKNOWN (delivery stage) and SENT are recorded for the sender, UNKNOWN and RECEIVED for the recipient, and FIRST_OPENED and VIEWED when the recipient opens it. SENT and RECEIVED are recorded once per recipient. Events of the same mail share the same msg_id.

Information that Google does not provide and how events are actually recorded:

• The sender address, attachment names and URLs of clicked links are not in the response. For mail sent within the organization, you can find the sender from the SENT event with the same msg_id, as in the example below.
• mail_to does not distinguish To, Cc and Bcc.
• A bounce is recorded as an event whose mail_event_type is UNKNOWN and action_type is BOUNCED, not as BOUNCED.
• Forwarding records FIRST_REPLIED on the original mail, not FIRST_FORWARDED.
• Auto-forwarding records an AUTOFORWARDED event together with a SENT event (without src_ip) to the forwarding address. mail_to of AUTOFORWARDED is the forwarding user, and the actual destination is in that SENT event.
• Mail sent to a group address is recorded with the group address as user.
• Opening a thread also records VIEWED for earlier mails in the thread.
• Marking as read, downloading a mail, and blocking the sender when reporting spam are not recorded.
• UNKNOWN (delivery stage) events make up about half of all events.
• mail_attachment_count is set only on SENT and delivery stage events, and src_ip is empty for some events.

If the user option specifies a user that does not exist, the result is empty without an error.

Examples

Example: Mails sent in the last day

Situation: Check mails sent by users in the last day and their attachment counts.

google-workspace-gmail-logs profile=google_workspace duration=1d
| search mail_event_type == "SENT"
| fields _time, user, src_ip, mail_to, mail_subject, mail_attachment_count

Expected result:

Interpretation: A SENT event without src_ip is a mail that the user did not send directly, such as an auto-forward or a Google notification.

Example: Event counts by type for a user

Situation: Count a user's mail activity in the last week by event type.

google-workspace-gmail-logs profile=google_workspace user=user1@example.com duration=7d
| stats count by mail_event_type
| sort -count

Expected result:

Interpretation: UNKNOWN is a mail delivery stage record. For the user's actual activity, look at SENT, RECEIVED, FIRST_OPENED, VIEWED and so on.

Example: Find the sender of mail received from within the organization

Situation: RECEIVED events have no sender, so find the sender from the SENT event with the same msg_id.

google-workspace-gmail-logs profile=google_workspace duration=7d
| search mail_event_type == "RECEIVED"
| join msg_id [
    google-workspace-gmail-logs profile=google_workspace duration=7d
    | search mail_event_type == "SENT" and isnotnull(src_ip)
    | stats first(user) as sender by msg_id ]
| fields _time, user, sender, mail_subject

Expected result:

Interpretation: Mail received from outside has no SENT event and does not appear in the result. To see all received mail, use join type=left; sender is empty for external mail.

Example: Check auto-forwarding destinations

Situation: Check whether mail is auto-forwarded outside the organization.

google-workspace-gmail-logs profile=google_workspace duration=7d
| search mail_event_type == "AUTOFORWARDED"
| join msg_id, user [
    google-workspace-gmail-logs profile=google_workspace duration=7d
    | search mail_event_type == "SENT" and isnull(src_ip)
    | stats values(mail_to) as forward_to by msg_id, user ]
| fields _time, user, mail_subject, forward_to

Expected result:

Interpretation: If forward_to is an external domain, mail is being auto-forwarded outside the organization. Check with the user whether the setting is intended.