G Suite Email Audit API Developer's Guide

The G Suite Email Audit API allows G Suite administrators to audit a user's email, email drafts, and archived chats. In addition, a domain administrator can download a user's mailbox. This API can be used only for lawful purposes in accordance with your Customer Agreement.
This API only applies to G Suite, Education, and ISPs accounts. It is not used with a G Suite or Gmail account not hosted by the G Suite products.

Note: You must enable API access from the G Suite Admin console to be able to make any calls to the G Suite Email Audit API. To enable the API, log in to your admin account and select Security. If you do not see Security listed, select More controls and then select Security from the options shown in the gray box. Select API reference, and then select the checkbox to Enable API access. Save your changes.

Managing Email Monitors

Types of users in a monitored email scenario

A monitored email scenario includes three types of users:

Administrator — Any domain administrator can create, retrieve, update, and delete an email monitor using the Email Audit API's monitor resource. 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.

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 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 is not 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 [Updating an email monitor][#uploading_the_public_key].

Creating a new email monitor

To begin an audit, use the API's email monitor resource. To create an email monitor, send the following POST request.

The destUserName is the destination user, the user name (not the full email address) who receives copies of the messages. This is the user auditing the messages. For example, in the example.com domain, to make namrata@example.com the destination user, use name='destUserName' value='namrata'. This is a required element. For more information about the destination user, see Types of users in an audited email scenario.

If more than one API monitor is created for the same 'destination user - source user' pair, the settings of the last monitor are retained. This is how you update the audited email configuration. For information about updating, see Updating an email monitor.

beginDate

The beginDate is the date when the audit starts. This is an optional element. If this element is an empty string, the email auditing begins immediately with the current date. And in this case, the endDate property's value must be greater than the current date.

:

* The date format is yyyy-MM-dd HH:mm where the HH is the hour of the day using 0 - 23, and the mm is the minutes of the hour using 0 - 59.

The HH:mm time zone is in Coordinated Universal Time (UTC) format. Convert your time to UTC format before creating a new monitor.

This date must be the current date or a future date. Otherwise, an error is returned.

endDate

The endDate is the date when the audit stops. This is a required element.

Using the same syntax as the beginDate parameter, the endDate format is yyyy-MM-dd HH:mm where the HH is the hour of the day using 0 - 23, and the mm is the minutes of the hour using 0 - 59.

The HH:mm time zone is in Coordinated Universal Time (UTC) format. Convert your time to UTC format before creating a new monitor.

An endDate value must be greater than your beginDate property's value. If the beginDate is not specified, the current date becomes the beginDate property's value. In this case, the endDate must be greater than the current date.

incomingEmailMonitorLevel

The incomingEmailMonitorLevel is the amount of audited information captured for incoming emails. This is an optional element. If no value is entered, the default is FULL_MESSAGE.

FULL_MESSAGE — The full incoming email body is sent to the destination user.

HEADER_ONLY — Only the incoming email's header information is sent to the destination user.

outgoingEmailMonitorLevel

The outgoingEmailMonitorLevel is the amount of monitored information captured for outgoing emails. This is an optional element. If no value is entered, the default is FULL_MESSAGE.

FULL_MESSAGE — The full outgoing email body is sent to the destination user.

HEADER_ONLY — Only the outgoing email's header information is sent to the destination user.

draftMonitorLevel

The draftMonitorLevel is the amount of audit information captured for draft emails. This is an optional element. If no value or the empty string is provided for this element, no email drafts are audited. NONE is the default.

FULL_MESSAGE — The full draft email body is sent to the destination user.

HEADER_ONLY — Only the draft email's header is sent to the destination user.

chatMonitorLevel

The chatMonitorLevel is the amount of audit information captured for archived chats. This is an optional element. If no value or the empty string is provided for this element, no email drafts are audited. This is the default.

FULL_MESSAGE — The full chat text is sent to the destination user.

HEADER_ONLY — Only the chat's header is sent to the destination user.

Note: 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.

If successful, the server returns a `201 CREATED` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response includes an AtomPub entry with the entry element showing new monitor settings.

Example for updating an email monitor

This example updates the monitor created above by updating the required property endDate and the optional property chatMonitorLevel. We'll use the following settings:

The new endDate is August 30, 2009, 23:20 hours.

The chatMonitorLevel is now HEADER_ONLY.

The user to be audited remains abhishek@example.com.

The destUserName remains namrata.

Note: The monitor properties that were not 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.

If successful, the server returns a `201 CREATED` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response includes an AtomPub entry with the updated entry elements. The properties that were not updated and shown in the response revert to their default values.

Retrieving 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, and using the UTC format for the date. Include the Authorization header as described in Authenticating requests:

This operation has no parameters in the request body. The XML body is empty.

Example for retrieving all email monitors

This example retrieves all the monitors created for the user abhishek@example.com.

Protocol

GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek

If successful, the server returns a 201 CREATED status code found in the Google Data API HTTP status codes documentation. In this example, along with the status code, the response includes an AtomPub feed with the entry elements for 2 monitors showing the settings for 2 destination users (namrata@example.com, joe@example.com).

Accessing Account Information

Warning: Account Information is not available in Email Audit API starting from August 1, 2017. Please use
Reports API
instead.

Managing a Mailbox Download

Downloading a mailbox

Administrators can download mailbox accounts within their domain for audit purposes. To prepare a mailbox for export, the Email Audit service creates an encrypted copy of a user's mailbox. When the export preparation is completed, the system returns the URLs to the encrypted mailbox files which, when downloaded and decrypted, are available in mbox format. The downloading steps are:

Upload a public key — The administrator provides a public encryption key for downloading mailboxes. The creation of this public key is only done once. If you have already created a public key for accessing account information, you do not need to complete this step. This public encryption key is in Pretty Good Privacy (PGP) format using the ASCII-encoded RSA key encryption. One way this key can be generated is to use GNU Privacy Guard (GPG) from www.gnupg.org. If using GPG, specify the --expert flag in order to generate an RSA encryption key. Export the public part of the GPG key using gpg --armor --export. This key is used to encrypt the mailbox export files available through HTTP URLs.

Create an export version of a user's mailbox — The mailbox export process starts when an administrator requests the creation of a copy of a user's mailbox. The Email Audit API's operation authenticates and authorizes the administrator's credentials and returns a unique request id. The mailbox creation process can be time consuming and may take several days depending upon the mailbox size.

Obtain the downloaded mailbox files — After downloading the encrypted files, the administrator decrypts the mailbox files using the domain's private key. Once decrypted, the files are viewed in mbox format.

Note: Google retains the encrypted mailbox files for 3 weeks. After that time, they are deleted. It is the responsibility of the domain administrator to download these mailbox files within this time period. To delete these mailbox files before the time period has expired, use the Deleting an encrypted mailbox operation.

Creating a mailbox for export

To prepare a copy of a user's mailbox for export and downloading, use the Email Audit API's export feed. Before using this operation, confirm you have successfully uploaded a public encryption key for your domain.

Send a POST request to the export feed's URI. Include the Authorization header as described in Authenticating requests:

The beginDate is the date for the first email included in the exported mailbox. This is an optional element. If you want all emails starting from when the account was created, do not enter a value for this field.

The date format is yyyy-MM-dd HH:mm where the HH is the hour of the day using 0 - 23, and the mm is the minutes of the hour using 0 - 59.

The HH:mm time zone is in Coordinated Universal Time (UTC) format. Convert your time to UTC format before creating a new monitor.

endDate

The endDate is the date for the last email included in the exported mailbox. This is an optional element. If the endDate is not specified or an empty string, the exported emails go up to the current date.

Using the same syntax as the beginDate parameter, the endDate format is yyyy-MM-dd HH:mm where the HH is the hour of the day using 0 - 23, and the mm is the minutes of the hour using 0 - 59.

The HH:mm time zone is in Coordinated Universal Time (UTC) format. Convert your time to UTC format before creating a new monitor.

Remember, an endDate value must be greater than your beginDate property's value.

searchQuery

The mailbox is filtered using this searchQuery value and only the filtered search results will be available for download. This is an optional element. These queries follow the same search rules as a Gmail's advanced search.

Note: The searchQuery and includeDeleted parameters are mutually exclusive. A search query is not possible if includeDeleted = "true".

includeDeleted

The includeDeleted parameter determines whether or not deleted messages are included in the mailbox export file. This is an optional element and, by default, the value is 'false', deleted messages are not included.

packageContent

The packageContent determines whether the full email or the email's header are used in the mailbox export file.

FULL_MESSAGE — The full email text, including attachments, is copied to the export file. This is the default setting for the packageContent element.

HEADER_ONLY — Only the email's header is copied to the export file.
Note: The maximum mailbox export creation requests per day is a total of 100 requests from all domain administrators. The mailbox creation process can be time consuming and may take several days depending upon the mailbox size. To see the status of the mailbox creation process, use the Retrieving the export status of a mailbox operation including the requestId value.

Retrieving the export status of a mailbox

To retrieve status details for a mailbox prepared for export, send an HTTP GET request with the mailbox's requestId to the export feed's URI. Include the Authorization header as described in Authenticating requests:

The mailbox files were deleted by Google after the 3 week retention limit.

Note: A requestId is a unique identifier for the mailbox export request that is returned when the export file is created.Note: Since a mailbox export preparation is an asynchronous process, use this retrieval request to see if the encrypted mailbox processing was completed.

Example for retrieving the export status of a mailbox

This example retrieves the mailbox status corresponding to the requestIds 53156 and 34201 for the user liz@example.com.

Protocol

GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/53156

This second example was successful with a COMPLETED status. It returns 2 mailbox file URLs containing the encrypted mailbox files The encrypted mailbox files which can be downloaded using the URLs in the fileUrl elements.

Retrieving all mailbox status requests

To retrieve all mailbox requests for a domain starting on a particular date which is in UTC format, make an HTTP GET request to the export feed URI. Include the Authorization header as described in Authenticating requests:

GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/{domain name}?fromDate={fromDate}

Note: The fromDate is the URL-encoded date of an encrypted mailbox request in UTC. If no fromDate is specified in this GET request, all requests in the past 3 weeks are retrieved.Note: For a large response, each page of results returns a maximum of 100 entries, and includes a URI in a <link rel='next'...> tag pointing to the next page of results. When developing your client application, your code needs to manage these additional results.

Example for retrieving all mailbox status requests

In this example, we will retrieve all mailbox status requests for the domain example.com made on or after 9 PM, August 30, 2009.

Deleting an encrypted mailbox

To delete the encrypted mailbox files, make an HTTP DELETE request to the export feed's URI including the requestId of the mailbox. Also, include the Authorization header as described in Authenticating requests.

Note: This operation deletes mailbox files with status as COMPLETED or MARKED_DELETED. For more information, see Retrieving the export status of a mailbox.Note: When a user invokes this operation and errors are encountered during the deletion process, the status of MARKED_DELETE status is returned. This request will be automatically taken up for deletion again by a cleanup job running at Google within 24 hours. However for a request with status MARKED_DELETE, some (or all) mailbox files may still be available for download. If the administrator wants to make sure that the files are deleted then they should invoke this operation again till the DELETED status is returned. If the status of MARKED_DELETE is returned consistently, then the administrator should retry after exponential time back offs.

Example for deleting an encrypted mailbox

In this example, we will delete the mailbox for the user liz@example.com corresponding to the requestId 34201.