To set up email monitoring with the Email Audit API, an adminstrator sets a date range for the auditor to receive a copy of a particular user's sent and received emails as an attachment. The maximum number of monitor creation and deletion requests per day is 1000 requests. This limit is per domain, and includes all requests made by any administrator during the day.
A monitored email scenario includes three types of users:
Administrator — Any domain administrator can create, retrieve, update, and delete an email monitor using the monitor resource of the Email Audit API. In addition, an administrator can use the API to download the mailbox. These operations can only be done within the domain over which the administrator exercises control.
Source user — The source user is the user who receives or sends messages that are being audited by the monitoring destination user. Any domain administrator or account user can be a source user. The source user must be in the same domain as the administrator and destination user.
Destination user — The destination user is the auditor who receives the audited email messages.
- Receives blind carbon copies (Bcc) of all incoming and outgoing email messages including inbound and outbound attachments, forwarded messages, and email messages sent from mobile devices.
- As an option, a domain administrator can enable additional auditing features for the destination user. The optional features include the auditing of saved email drafts, the auditing of archived Hangouts chats with other users who can be in or outside of the domain.
- Even though the destination user receives a Bcc copy of the message, the Bcc association isn't visible in the message headers accessible in the source user's account.
- Each audited email message is sent to the destination user as an email attachment. And the domain administrator can configure these messages to be either the full email message or only the message headers.
- This destination user must have an active email account in the monitored domain. This must be the same domain associated with the administrator and source user.
- A destination user can be an administrator or a user within the domain. And, this destination user can switch roles to become a source user audited by another destination user who, in turn, receives copies of all audited email messages sent to the first destination user.
- A domain administrator creates one audited email monitor for one unique 'destination user - source user' pair. In other words, the audit relationship is one destination user to one source user. Each audit is done using an API monitor resource. Using multiple API monitors, a destination user can audit many users in the domain. And, using multiple API monitors, many destination users can audit one source user.
- If an additional API monitor is created or an existing API monitor is updated for a 'destination user - source user' pair, the monitor which was the last created supersedes any pre-existing monitors for this pair. Basically, this is how you update an API monitor. For more information about updating a monitor, see Update an email monitor.
Create an email monitor
To create an email monitor, send the following POST
request with the email
monitor resource:
POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/DOMAIN_NAME/SOURCE_USERNAME
Replace the following:
DOMAIN_NAME
: the Google Workspace domain name—for example, example.com.SOURCE_USERNAME
: the username that you want to monitor.
The POST
request contains the following Content-type
header:
Content-type: application/atom+xml
For a full list of parameters to use in an email monitor request, see
Resources: monitor
.
Example for creating a new monitor
The example uses the following parameters:
- The user to be audited is
amal@example.com
. - The
destUserName
isizumi
. - The
beginDate
isJune 15, 2022, 00:00 hours
. - The
endDate
isJune 30, 2022, 23:20 hours
. - The
incomingEmailMonitorLevel
isFULL_MESSAGE
. - The
outgoingEmailMonitorLevel
isHEADER_ONLY
. - The
draftMonitorLevel
isFULL_MESSAGE
. - The
chatMonitorLevel
isFULL_MESSAGE
.
Protocol
POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal <atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'> <apps:property name='destUserName' value='izumi'/> <apps:property name='beginDate' value='2022-06-15 00:00'/> <apps:property name='endDate' value='2022-06-30 23:20'/> <apps:property name='incomingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='outgoingEmailMonitorLevel' value='HEADER_ONLY'/> <apps:property name='draftMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='chatMonitorLevel' value='FULL_MESSAGE'/> </atom:entry>
If successful, the server returns a 201 CREATED
status code and
an AtomPub entry with the entry
element showing new monitor
settings:
<entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'> <id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/id</id> <updated>2022-04-17T15:02:45.646Z</updated/> <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/id'/> <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/id'/> <apps:property name='destUserName' value='izumi'/> <apps:property name='beginDate' value='2022-06-15 00:00'/> <apps:property name='endDate' value='2022-06-30 23:20'/> <apps:property name='incomingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='outgoingEmailMonitorLevel' value='HEADER_ONLY'/> <apps:property name='draftMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='chatMonitorLevel' value='FULL_MESSAGE'/> </entry>
Java
import java.util.Calendar; import com.google.gdata.client.appsforyourdomain.audit.AuditService; import com.google.gdata.data.appsforyourdomain.generic.GenericEntry; import com.google.gdata.client.appsforyourdomain.audit.MailMonitor; ... MailMonitor monitor = new MailMonitor(); Calendar beginDate = Calendar.getInstance(); beginDate.set(2022, Calendar.JUNE, 15, 0, 0) monitor.setBeginDate(beginDate.getTime()); Calendar endDate = Calendar.getInstance(); endDate.set(2022, Calendar.JUNE, 30, 23, 20); monitor.setEndDate(endDate.getTime()); monitor.setIncomingEmailMonitorLevel("FULL_MESSAGE"); monitor.setOutgoingEmailMonitorLevel("HEADER_ONLY"); monitor.setDraftMonitorLevel("FULL_MESSAGE"); monitor.setChatMonitorLevel("FULL_MESSAGE"); monitor.setDestUserName("izumi"); AuditService service = new AuditService("admin@example.com", "p@55w0rd", "example.com", "example.com-auditapp-v1"); GenericEntry entry = service.createMailMonitor("amal", monitor);
.NET
using System; using Google.GData.Apps; using Google.GData.Extensions.Apps; ... MailMonitor monitor = new MailMonitor(); monitor.BeginDate = new DateTime(2022, 6, 15); monitor.EndDate = new DateTime(2022, 6, 30, 23, 20, 0); monitor.IncomingEmailMonitorLevel = MonitorLevel.FULL_MESSAGE; monitor.OutgoingEmailMonitorLevel = MonitorLevel.HEADER_ONLY; monitor.DraftMonitorLevel = MonitorLevel.FULL_MESSAGE; monitor.ChatMonitorLevel = MonitorLevel.FULL_MESSAGE; monitor.DestinationUserName = "izumi"; AuditService service = new AuditService("example.com", "example.com-auditapp-v1"); service.setUserCredentials("admin@example.com", "p@55w0rd"); MailMonitor monitorEntry = service.CreateMailMonitor("amal", monitor);
Update an email monitor
When updating a monitor with the same source user and destination user, the initial monitor's property settings are replaced by the new settings.
To update the audit configuration in an email monitor, send a POST
request to
the monitor feed's URI and include the Authorization
header:
POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/DOMAIN_NAME/SOURCE_USERNAME
Replace the following:
DOMAIN_NAME
: the Google Workspace domain name—for example, example.com.SOURCE_USERNAME
: the username of the email monitor that you want to update.
Example for updating an email monitor
This example updates the monitor created in the
example for creating an email monitor
by updating the required property endDate
and the optional property
chatMonitorLevel
. This example uses the following parameters:
- The new
endDate
isAugust 30, 2022, 23:20 hours
. - The
chatMonitorLevel
is nowHEADER_ONLY
. - The user to be audited remains
amal@example.com
. - The
destUserName
remainsizumi
.
The monitor properties that weren't updated revert to their default values. For
instance, in this example, the incomingEmailMonitorLevel
and
outgoingEmailMonitorLevel
properties revert to FULL_MESSAGE
, and the
draftMonitorLevel
reverts to NONE
.
Protocol
POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal <atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'> <apps:property name='destUserName' value='izumi'/> <apps:property name='endDate' value='2022-08-30 23:20'/> <apps:property name='chatMonitorLevel' value='HEADER_ONLY'/> </atom:entry>
If successful, the server returns a 201 CREATED
status code and
an AtomPub entry with the updated entry
elements. The properties
that weren't updated and shown in the response revert to their default values.
<entry> <entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'> <id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi</id> <updated>2022-08-20T00:28:57.319Z</updated> <link rel='self' type='application/atom+xml' href="https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi" /> <link rel='edit' type='application/atom+xml' href="https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi" /> <apps:property name='chatMonitorLevel' value='HEADER_ONLY' /> <apps:property name='destUserName' value='izumi' /> <apps:property name='endDate' value='2022-08-30 23:20' /> </entry>
Java
import java.util.Calendar; import com.google.gdata.client.appsforyourdomain.audit.AuditService; import com.google.gdata.client.appsforyourdomain.audit.MailMonitor; import com.google.gdata.data.appsforyourdomain.generic.GenericEntry; ... MailMonitor monitor = new MailMonitor(); Calendar endDate = Calendar.getInstance(); endDate.set(2022, Calendar.AUGUST, 30, 23, 20); monitor.setEndDate(endDate.getTime()); monitor.setChatMonitorLevel("HEADER_ONLY"); monitor.setDestUserName("izumi"); AuditService service = new AuditService("admin@example.com", "p@55w0rd", "example.com", "example.com-auditapp-v1"); GenericEntry entry = service.createMailMonitor("amal", monitor);
.NET
using System; using Google.GData.Apps; using Google.GData.Extensions.Apps; ... MailMonitor monitor = new MailMonitor(); monitor.EndDate = new DateTime(2022, 8, 30, 23, 20, 0); monitor.ChatMonitorLevel = MonitorLevel.HEADER_ONLY; monitor.DestinationUserName = "izumi"; AuditService service = new AuditService("example.com", "example.com-auditapp-v1"); service.setUserCredentials("admin@example.com", "p@55w0rd"); MailMonitor monitorEntry = service.CreateMailMonitor("amal", monitor);
Retrieve all email monitors of a source user
To retrieve all monitors associated with a source user, make an HTTP GET
request to the monitor feed URI, using the UTC format for the date, and include
the Authorization
header:
GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/DOMAIN_NAME/SOURCE_USERNAME
Replace the following:
DOMAIN_NAME
: the Google Workspace domain name—for example, example.com.SOURCE_USERNAME
: the username of the email monitor that you want to retrieve.
This operation has no parameters in the request body, so the XML body is empty.
Example for retrieving all email monitors
This example retrieves all the monitors created for the user amal@example.com
:
Protocol
GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal
If successful, the server returns a 201 CREATED
status code and
an AtomPub feed with the entry
elements for two monitors showing the
settings for two destination users (izumi@example.com,
taylor@example.com
).
<feed xmlns:atom='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:apps='http://schemas.google.com/apps/2006'> <id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal</id> <updated>2010-03-17T15:29:21.064Z</updated> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal'/> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal'/> <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal'/> <openSearch:startIndex>1</openSearch:startIndex> <entry> <id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi</id> <updated>2022-04-17T15:29:21.064Z</updated> <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi&'/> <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/feeds/compliance/audit/mail/monitor/example.com/amal/izumi&'/> <apps:property name='requestId' value='53156'/> <apps:property name='destUserName' value='izumi'/> <apps:property name='beginDate' value='2022-06-15 00:00'/> <apps:property name='endDate' value='2022-06-30 23:20'/> <apps:property name='incomingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='outgoingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='draftMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='chatMonitorLevel' value='FULL_MESSAGE'/> </entry> <entry> <id>>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/taylor</id> <updated>2022-05-17T15:29:21.064Z</updated> <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/taylor'/> <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/taylor'/> <apps:property name='requestId' value='22405'/> <apps:property name='destUserName' value='taylor'/> <apps:property name='beginDate' value='2022-06-20 00:00'/> <apps:property name='endDate' value='2022-07-30 23:20'/> <apps:property name='incomingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='outgoingEmailMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='draftMonitorLevel' value='FULL_MESSAGE'/> <apps:property name='chatMonitorLevel' value='FULL_MESSAGE'/> </entry> </feed>
Java
import com.google.gdata.client.appsforyourdomain.audit.AuditService; import com.google.gdata.data.appsforyourdomain.generic.GenericFeed; ... AuditService service = new AuditService("admin@example.com", "p@55w0rd", "example.com", "example.com-auditapp-v1"); GenericFeed feed = service.retrieveMonitors("amal");
.NET
using System; using System.Collections.Generic; using Google.GData.Apps; using Google.GData.Extensions.Apps; ... AuditService service = new AuditService("example.com", "example.com-auditapp-v1"); service.setUserCredentials("admin@example.com", "p@55w0rd"); GenericFeed<MailMonitor> monitors = service.RetrieveMailMonitors("amal");
Delete an email monitor
To delete an email monitor, make an HTTP DELETE
request to the monitor feed's
delete URI and include the Authorization
header:
DELETE https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/DOMAIN_NAME/SOURCE_USERNAME/DESTINATION_USERNAME
Replace the following:
DOMAIN_NAME
: the Google Workspace domain name—for example, example.com.SOURCE_USERNAME
: the username of the email monitor that you want to delete.DESTINATION_USERNAME
: the auditor who receives the audited email messages.
Example for deleting an email monitor
This example deletes the monitors created for the user amal@example.com
with destinationUserName
as izumi
.
Protocol
DELETE https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/amal/izumi
Java
import com.google.gdata.client.appsforyourdomain.audit.AuditService; ... AuditService service = new AuditService("admin@example.com", "p@55w0rd", "example.com", "example.com-auditapp-v1"); service.deleteMonitor("amal", "izumi");
.NET
using System; using Google.GData.Apps; using Google.GData.Extensions.Apps; ... AuditService service = new AuditService("example.com", "example.com-auditapp-v1"); service.setUserCredentials("admin@example.com", "p@55w0rd"); service.DeleteMailMonitor("amal", "izumi");