Purpose
This guide explains how to collect Gmail log events from Google Workspace into Logsign USO. The integration reads the Gmail activity log through the Google Admin SDK Reports API (activities.list with applicationName=gmail), using a Google Cloud service account with domain-wide delegation. It records mailbox activity such as messages sent and received, spam and quarantine actions, forwarding and autoforwarding, link clicks, attachment downloads and deletions.
Gmail is a separate source in Logsign, named Gmail in the API source list. It is not an activity of the existing G Suite source, so adding it does not change an existing G Suite source. Both sources use the same kind of service account and P12 key, so if you already collect G Suite logs you can reuse that service account.
Prerequisites
Google Cloud project and service account: a service account with a key in P12 format. Google protects every service account P12 key with the same fixed password, which Logsign already knows, so no password field is needed.
Domain-wide delegation: the service account's OAuth 2 Client ID must be authorized in the Google Workspace Admin console with the scope below. This is the only scope the Gmail source requests.
https://www.googleapis.com/auth/admin.reports.audit.readonly
Admin user to impersonate: an existing Google Workspace user who can read the audit and investigation reports in the Admin console (a super admin, or an admin role that includes the Reports privilege). Logsign acts on behalf of this user when it calls the Reports API. A regular user without admin rights cannot be used.
Google Workspace edition: the Gmail log events must be available in your Workspace edition. If they are not, Google rejects the request with HTTP 403 (see Troubleshooting). Check Google's edition comparison for "Gmail log events" before you start.
Network access: the Logsign server must reach https://oauth2.googleapis.com (token) and https://admin.googleapis.com (Reports API) over HTTPS.
Step 1: Create a Service Account in Google Cloud Console
If you already have a service account for the Logsign G Suite source, you can use it and skip to Step 2.
- Open the Google Cloud Console and select (or create) the project that will hold the service account.
- Go to IAM & Admin > Service Accounts and click Create service account. Give it a descriptive name, for example
logsign-gmail-logs. It does not need any Google Cloud IAM role. - Open the service account, go to Keys > Add key > Create new key, select P12 and download the file.
- Note the service account's email address (ending in
iam.gserviceaccount.com) and its OAuth 2 Client ID (the numeric Unique ID shown on the service account details page). You need the email in Logsign and the Client ID in the next step.
Step 2: Authorize Domain-wide Delegation in the Google Workspace Admin Console
- Sign in to the Google Admin console as a super admin.
- Go to Security > Access and data control > API controls and open Manage Domain Wide Delegation.
- Click Add new, enter the service account's OAuth 2 Client ID and add the scope
https://www.googleapis.com/auth/admin.reports.audit.readonly. - Click Authorize.
If the Client ID is already listed because you use the same service account for the G Suite source, it already has this scope and nothing needs to change. If you edit that entry, keep the scopes that are already there, since the G Suite source still needs them.
Google can take some time to apply a new delegation. If the first poll right after this step fails to get a token, wait a few minutes and let the next cycle retry.
Step 3: Configure the Source in Logsign USO
Go to Settings > Data Collection > API, add a new source and select Gmail. The form contains the following fields:
| Field | Value |
|---|---|
| Private Key File | Upload the .p12 file from Step 1. Only P12 files are accepted. |
| Service Account Email | The service account email address, for example logsign-gmail-logs@my-project.iam.gserviceaccount.com. |
| User Email | The admin user Logsign impersonates (see Prerequisites). This must be a real Workspace user, not the service account. |
| Excluded Event Types | Gmail event types that are not collected. By default 0 - Unknown, 29 - Draft saved and 31 - Message viewed are excluded. See "Choosing excluded event types" below. |
| Log Start Date | How far back the first run collects. Default 1 hour, up to 30 days. It cannot be changed after the source is saved. |
The common source fields (period, EPS, offset, source name and so on) work as for other API sources. Save the source to start collection.
When you delete a Gmail source in Logsign, its uploaded key file is deleted as well.
Choosing excluded event types
Gmail produces a large number of events. The three types excluded by default (unknown, draft saved, message viewed) account for roughly two thirds of the volume on a typical tenant and have little security value, so leaving them excluded keeps EPS and storage under control. You can remove any of them from the list, or add more types, in the source form.
The filter is applied by Logsign after the events are downloaded, because the Reports API accepts only one event type condition per request. Excluded events are still downloaded from Google, they are just not stored or processed in Logsign.
How Collection Works
- Time windows: Logsign reads Gmail events in windows of up to 60 minutes. A window is read completely, across all its pages (1,000 events per page), before Logsign moves on, so a window is never left half collected.
- 10 minute delay: Google makes some Gmail events available a few minutes after they happen. To avoid missing them, Logsign only reads windows that ended at least 10 minutes ago. Events therefore appear in Logsign with a delay of at least 10 minutes plus the polling period.
- Catching up: each polling cycle processes up to 24 windows (24 hours of activity). After a long outage or a large Log Start Date, the source catches up over several cycles.
- No duplicates on errors: if a request fails in the middle of a window (for example a 401, a quota error or a network problem), the position is not advanced and the whole window is read again on the next cycle.
What Gets Collected
Each event is classified according to its Gmail event type (event_info.mail_event_type). The type number is written to Event.ID and its name to Event.Action.
| Event type | Classification | Severity |
|---|---|---|
| 0 Unknown | Application / Mail / Other | information |
| 1 Message sent | Application / Mail / Send | information |
| 2 Message received | Application / Mail / Receive | information |
| 3 Marked as spam by user, 4 Marked as spam after delivery | Security / Spam / Detect | warning |
| 5 Message quarantined | Security / Spam / Quarantine | warning |
| 6 Released from quarantine | Application / Mail / Deliver | information |
| 7 Message opened, 8 Marked as unread, 9 Message replied, 12 Moved to inbox, 14 Removed from trash, 15 Link clicked, 16 Attachment link clicked, 26 Message archived, 29 Draft saved, 31 Message viewed, 33 Message accessed by application | Application / Mail / Info | information |
| 10 Message forwarded | Application / Mail / Redirect | information |
| 11 Message autoforwarded | Application / Mail / Redirect | warning |
| 13 Moved to trash | Application / Mail / Delete | information |
| 27 Message permanently deleted | Application / Mail / Delete | warning |
| 17 Attachment downloaded, 28 Attachment previewed, 32 Message downloaded | Object / File / Access | information |
| 18 Attachment saved to Drive, 19 Drive item saved to Drive | Object / File / Create | information |
| 20 to 25 (label and attachment label applied, changed, removed) | Application / Mail / Status | information |
| 30 Message bounced | Application / Mail / Fail | warning |
| 34 Receive rate limited | Application / Mail / Block | warning |
| 35 Send initiated | Application / Mail / Submit | information |
Events appear in Logsign with the event source Google / Gmail (type Cloud Computing, category Mail Security).
Field mappings
| Gmail field | Logsign field |
|---|---|
| id.time | Time.Generated |
| actor.email | Source.UserName |
| actor.email (only for event type 1, Message sent) | Mail.FROM |
| actor.callerType | Source.UserType |
| actor.applicationInfo.applicationName | Application.Name |
| ipAddress | Source.IP |
| event_info.mail_event_type | Event.ID |
| event type name | Event.Action |
event_info.success (success or failure) | Event.Status |
| message_info.action_type | Event.Info |
message_info.is_spam (written as spam) | Event.Situation |
| recipient addresses from message_info.flattened_destinations | Mail.TO |
| message_info.subject | Mail.Subject |
| message_info.rfc2822_message_id | Mail.MessageID |
| message_info.payload_size | Mail.Size |
| message_info.num_message_attachments | Mail.AttachCount |
| message_info.description (SMTP reply) | Mail.Status |
| rule names from message_info.flattened_triggered_rule_info | Rule.Name |
| message_info.link_domain | URL.Domain |
When a field contains several values (recipients, rule names, link domains), they are written comma separated.
Limits of the Reports API
The Gmail data available through the Reports API is narrower than the Gmail log events you see in the Admin console or in a BigQuery export. Keep the following in mind when you plan alert rules:
- No sender for received mail: for received messages the actor is the recipient mailbox, and Google does not return the sender address.
Mail.FROMis only filled for sent messages. - No authentication or attachment details: Google does not fill the source, destination, connection, attachment and spam detail blocks through this API. SPF, DKIM and DMARC results, attachment names and hashes, and malware verdicts are therefore not available. They are only available in the Gmail logs exported to BigQuery, which this integration does not use.
- Delay: events arrive with a delay of at least 10 minutes, as described above.
Troubleshooting
Errors are written to the poller log of the source.
| Message or symptom | Likely cause | What to check |
|---|---|---|
Please ensure that all required config fields are set. | The key file, Service Account Email or User Email is missing. | Open the source and fill in all three fields. |
Google service account key file not found, could not be loaded or No private key found in the .p12 file | The uploaded key file is missing or is not a valid Google P12 key. | Delete the key in the source form and upload the P12 file downloaded from Google Cloud Console again. |
Failed to acquire access token. | Google refused to issue a token. Usually the delegation is missing or does not include the audit scope, the Service Account Email does not match the key, or the User Email is not an existing Workspace user. | Check the domain-wide delegation entry (Client ID and scope) and both email fields. A new delegation can take a few minutes to become active. |
Unauthorized - invalidating cached access token. (HTTP 401) | The cached token expired or was revoked. | No action is needed if it happens once; a new token is requested on the next cycle. If it repeats, check the delegation and the service account key status. |
Unexpected response from server. Status code: 403 | The scope is not delegated, the User Email is not an admin with access to reports, or Gmail log events are not available in your Workspace edition. | Check the user's admin role and the delegation. The response text in the log contains Google's reason. |
Unexpected response from server. Status code: 429 or 503 | Google's Reports API quota was exceeded. | The window is retried automatically on the next cycle. If it persists, increase the polling period. |
Gmail window ... exceeded 100 pages; the oldest events of this window were skipped. | More than 100,000 events, excluded types included, fell into a single 60 minute window. | This only happens on very large tenants. Contact Logsign support; excluding event types does not help here because filtering happens after download. |
| Source runs without errors but no events appear | Events are collected with a delay of at least 10 minutes, or all events in the period are of excluded types. | Wait for the next cycles and review the Excluded Event Types list. |