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.

The G Suite Email Audit API supports the Google Data API protocol. The Google Data API conforms to the Atom Publishing Protocol (AtomPub) publishing and editing model. The AtomPub HTTP requests use the Representational Set Transfer (RESTful) design approach to web services. For more information, see the Google Data APIs Developer Overview.

Audience

This document is intended for programmers who want to write client applications that, for lawful auditing purposes, can audit a G Suite user's mailbox.

This document assumes that you are a G Suite domain administrator and that you understand the general ideas behind the Google Data API protocol, and that you are familiar with your G Suite Admin console found at admin.google.com. For more information about the Admin console, see Use your Admin console.

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.

  • A destination user receives blind carbon copies (Bcc) of all incoming and outgoing email messages including inbound/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 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.

POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/{domain name}/{source user name}

The POST request contains the following Content-type header:

Content-type: application/atom+xml

The request parameters are:

destUserName

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 [e-mail] 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.

• Only one API monitor exists for a unique 'destination user - source user' pair.

• 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.

Example for creating a new monitor

In this example

• The user to be audited is [e-mail].
• The destUserName is namrata.
• The beginDate is June 15, 2009, 00:00 hours.
• The endDate is June 30, 2009, 23:20 hours.
• The incomingEmailMonitorLevel is FULL_MESSAGE.
• The outgoingEmailMonitorLevel is HEADER_ONLY.
• The draftMonitorLevel is FULL_MESSAGE.
• The chatMonitorLevel is FULL_MESSAGE.

Protocol

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

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
   <apps:property name='destUserName' value='namrata'/>
   <apps:property name='beginDate' value='2009-06-15 00:00'/>
   <apps:property name='endDate' value='2009-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 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.

<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/abhishek/id</id>
    <updated>2009-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/abhishek/id'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek/id'/>
    <apps:property name='destUserName' value='namrata'/>
    <apps:property name='beginDate' value='2009-06-15 00:00'/>
    <apps:property name='endDate' value='2009-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(2009, Calendar.JUNE, 15, 0, 0)
monitor.setBeginDate(beginDate.getTime());
Calendar endDate = Calendar.getInstance();
endDate.set(2009, 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("namrata");

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
GenericEntry entry = service.createMailMonitor("abhishek", monitor);

.NET

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

MailMonitor monitor = new MailMonitor();
monitor.BeginDate = new DateTime(2009, 6, 15);
monitor.EndDate = new DateTime(2009, 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 = "namrata";

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
MailMonitor monitorEntry = service.CreateMailMonitor("abhishek", monitor);

Updating an email monitor

When updating a monitor with the same source user and destination user, the old 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. Include the Authorization header as described in Authenticating requests:

POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/{domain name}/{source user name}

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 [e-mail].
• 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.

Protocol

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

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
    <apps:property name='destUserName' value='namrata'/>
    <apps:property name='endDate' value='2009-08-30 23:20'/>
    <apps:property name='chatMonitorLevel' value='HEADER_ONLY'/>
</atom:entry>

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.

<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/abhishek/namrata</id>
    <updated>2009-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/abhishek/namrata" />
    <link rel='edit' type='application/atom+xml' href="https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek/namrata" />
    <apps:property name='chatMonitorLevel' value='HEADER_ONLY' />
    <apps:property name='destUserName' value='namrata' />
    <apps:property name='endDate' value='2009-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(2009, Calendar.AUGUST, 30, 23, 20);
monitor.setEndDate(endDate.getTime());
monitor.setChatMonitorLevel("HEADER_ONLY");
monitor.setDestUserName("namrata");

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
GenericEntry entry = service.createMailMonitor("abhishek", monitor);

.NET

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

MailMonitor monitor = new MailMonitor();
monitor.EndDate = new DateTime(2009, 8, 30, 23, 20, 0);
monitor.ChatMonitorLevel = MonitorLevel.HEADER_ONLY;
monitor.DestinationUserName = "namrata";

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
MailMonitor monitorEntry = service.CreateMailMonitor("abhishek", monitor);

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:

GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/{domain name}/{source user name}

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 [e-mail].

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 ([e-mail], [e-mail]).

<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/abhishek</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/abhishek'/>
    <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/abhishek'/>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek'/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <entry>
        <id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek/namrata</id>
        <updated>2009-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/abhishek/namrata&'/>
        <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/feeds/compliance/audit/mail/monitor/example.com/abhishek/namrata&'/>
        <apps:property name='requestId' value='53156'/>
        <apps:property name='destUserName' value='namrata'/>
        <apps:property name='beginDate' value='2009-06-15 00:00'/>
        <apps:property name='endDate' value='2009-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/abhishek/joe</id>
        <updated>2009-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/abhishek/joe'/>
        <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/example.com/abhishek/joe'/>
        <apps:property name='requestId' value='22405'/>
        <apps:property name='destUserName' value='joe'/>
        <apps:property name='beginDate' value='2009-06-20 00:00'/>
        <apps:property name='endDate' value='2009-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("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
GenericFeed feed = service.retrieveMonitors("abhishek");

.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("[e-mail]", "p@55w0rd");
GenericFeed<MailMonitor> monitors = service.RetrieveMailMonitors("abhishek");

Deleting an email monitor

To delete an email monitor, make an HTTP DELETE request to the monitor feed's delete URI. Include the Authorization header as described in Authenticating requests.

DELETE https://apps-apis.google.com/a/feeds/compliance/audit/mail/monitor/{domain name}/{source user name}/{destination user name}

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.

Example for deleting an email monitor

This example deletes the monitors created for the user [e-mail] with destinationUserName as namrata.

Protocol

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

Java

import com.google.gdata.client.appsforyourdomain.audit.AuditService;
...

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
service.deleteMonitor("abhishek", "namrata");

.NET

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
service.DeleteMailMonitor("abhishek", "namrata");

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.
• Retrieve the mailbox download status or retrieve all mailbox status using a date — Use the mailbox export request ID to get the status of the pending request. Once the mailbox is copied and prepared for export, the response returns a status of COMPLETED along with the list of encrypted mailbox files as HTTP URLs. Use this set of URLs to download the mailbox files.
• 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:

POST https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/{domain name}/{source user name}

The request contains the following Content-type header:

Content-type: application/atom+xml

The request accepts the following properties as input:

beginDate

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.

Example for creating a mailbox for export

We'll use the following settings in this example:

• The user to export the mailbox for is [e-mail].
• The beginDate is July 1, 2009, 04:30 hours.
• The endDate is August 30, 2009, 20:00 hours.
• includeDeleted is false.
• searchQuery is in:chat.
• The packageContent is FULL_MESSAGE.

Protocol

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

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
   <apps:property name='beginDate' value='2009-07-01 04:30'/>
   <apps:property name='endDate' value='2009-08-30 20:00'/>
   <apps:property name='includeDeleted' value='false'/>
   <apps:property name='searchQuery' value='in:chat'/>
   <apps:property name='packageContent' value='FULL_MESSAGE'/>
</atom:entry>

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.

<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/export/example.com/liz/53156>/id>
    <updated>2009-10-17T15:02:45.646Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/53156'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/53156'/>
    <apps:property name='status' value='PENDING'/>
    <apps:property name='packageContent' value='FULL_MESSAGE'/>
    <apps:property name='includeDeleted' value='false'/>
    <apps:property name='searchQuery' value='in:chat'/>
    <apps:property name='completedDate' value='2009-09-18 10:13'/>
    <apps:property name='adminEmailAddress' value='[e-mail]'/>
    <apps:property name='requestId' value='53156'/>
    <apps:property name='userEmailAddress' value='[e-mail]'/>
    <apps:property name='endDate' value='2009-08-30 20:00'/>
    <apps:property name='requestDate' value='2009-09-17 12:51'/>
    <apps:property name='beginDate' value='2009-07-01 04:30'/>
</entry>

In this example, the processing of this mailbox has completed. The status property is COMPLETED and the numberOfFiles returned for export is 2.

Java

import java.util.Calendar;
import com.google.gdata.client.appsforyourdomain.audit.AuditService;
import com.google.gdata.client.appsforyourdomain.audit.MailBoxDumpRequest;
import com.google.gdata.data.appsforyourdomain.generic.GenericEntry;
...

MailBoxDumpRequest request = new MailBoxDumpRequest();
request.setAdminEmailAddress("[e-mail]");
request.setUserEmailAddress("[e-mail]");

Calendar beginDate = Calendar.getInstance();
beginDate.set(2009, Calendar.JULY, 1, 4, 30);
request.setBeginDate(beginDate.getTime());

Calendar endDate = Calendar.getInstance();
endDate.set(2009, Calendar.AUGUST, 30, 20, 0);
request.setEndDate(endDate.getTime());

request.setIncludeDeleted(false);
request.setSearchQuery("in:chat");
request.setPackageContent("FULL_MESSAGE");

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
GenericEntry mailboxDumpEntry = service.createMailboxDumpRequest(request);

String requestId = mailboxDumpEntry.getRequestId();
String status = mailboxDumpEntry.getStatus();
String numberOfFiles = mailboxDumpEntry.getNumberOfFiles();

.NET

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

MailboxDumpRequest mailboxDumpRequest = new MailboxDumpRequest();
mailboxDumpRequest.BeginDate = new DateTime(2009, 7, 1, 4, 30, 0);
mailboxDumpRequest.EndDate = new DateTime(2009, 8, 30, 20, 0, 0);
mailboxDumpRequest.IncludeDeleted = false;
mailboxDumpRequest.SearchQuery = "in:chat";
mailboxDumpRequest.PackageContent = MonitorLevel.FULL_MESSAGE;

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
MailboxDumpRequest dumpRequest = service.CreateMailboxDumpRequest("liz", mailboxDumpRequest);

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:

GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/{domain name}/{source user name}/{mailbox requestId}

This request returns an AtomPub entry including the current status of the mailbox. The possible values for the current status are:

PENDING

The request is being processed.

ERROR

The request failed due to some error. An example of a possible error is that a wrong PGP public key was uploaded for the domain.

COMPLETED

The request has been processed completely and the encrypted mailbox files are ready for download.

MARKED_DELETE

The request is marked for deletion next time the Google cleanup job runs. See Deleting an encrypted mailbox.

DELETED

The mailbox files were successfully deleted by the admin using Deleting an encrypted mailbox operation.

EXPIRED

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 [e-mail].

Protocol

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

<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/export/example.com/liz/53156</id>
    <updated>2009-10-17T15:02:45.646Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/53156'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/53156'/>
    <apps:property name='status' value='ERROR'/>
    <apps:property name='packageContent' value='FULL_MESSAGE'/>
    <apps:property name='includeDeleted' value='false'/>
    <apps:property name='searchQuery' value='in:chat'/>
    <apps:property name='completedDate' value='2009-09-18 10:13'/>
    <apps:property name='adminEmailAddress' value='[e-mail]'/>
    <apps:property name='numberOfFiles' value='0'/>
    <apps:property name='requestId' value='53156'/>
    <apps:property name='userEmailAddress' value='[e-mail]'/>
    <apps:property name='endDate' value='2009-08-30 20:00'/>
    <apps:property name='requestDate' value='2009-09-17 12:51'/>
    <apps:property name='beginDate' value='2009-07-01 04:30'/>
</entry>

If successful, the server returns a 201 CREATED status code found in the Google Data API HTTP status codes documentation.

As you can see from the response of the example above, the status is an ERROR and, therefore, the encrypted mailbox files were never created.

We'll try again for the requestId 34201:

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

<entry>...
    ...
    <apps:property name='status' value='COMPLETED'/>
    <apps:property name='packageContent' value='FULL_MESSAGE'/>
    <apps:property name='completedDate' value='2009-09-18 10:13'/>
    <apps:property name='adminEmailAddress' value='[e-mail]'/>
    <apps:property name='numberOfFiles' value='2'/>
    <apps:property name='requestId' value='34201'/>
    <apps:property name='userEmailAddress' value='[e-mail]'/>
    <apps:property name='requestDate' value='2009-09-17 12:51'/>
    <apps:property name='fileUrl0'  value='https://apps-apis.google.com/a/data/compliance/audit/OQAAABW3Z2OlwkDFR0H5n_6lnYAzv-pWlkAlbTyAzvJEV0MC4c7lBDW' />
    <apps:property name='fileUrl1'  value='https://apps-apis.google.com/a/data/compliance/audit/OQAAABW3Z2OlwkD55nLv-pWlkAlbTyAzvJEVPnVYW45C4cC34gtyVCC' />
</entry>

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.

Java

import com.google.gdata.client.appsforyourdomain.audit.AuditService;
import com.google.gdata.data.appsforyourdomain.generic.GenericEntry;
...

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
GenericEntry mailboxDumpEntry1 = service.retrieveMailboxDumpRequest("liz", "53156");
String status = mailboxDumpEntry1.getProperty("status"); // Status is "ERROR" if the mailbox for this request isn't created
GenericEntry mailboxDumpEntry2 = service.retrieveMailboxDumpRequest("liz", "34201");
String status = mailboxDumpEntry2.getProperty("status");

.NET

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
MailboxDumpRequest mailboxDumpEntry1 = service.RetrieveMailboxDumpRequest("liz", "53156");
RequestStatus status1 = mailboxDumpEntry1.Status; // Status is "ERROR" if the mailbox for this request isn't created
MailboxDumpRequest mailboxDumpEntry2 = service.RetrieveMailboxDumpRequest("liz", "34201");
RequestStatus status2 = mailboxDumpEntry2.Status;

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.

Protocol

<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/export/domain</id>
    <updated>2010-03-17T15:29:21.064Z</updated>
    <link rel='next' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/tapoloka.com?fromDate=2009-08-30%2021:00'/>
    <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/tapoloka.com'/>
    <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/tapoloka.com'/>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/tapoloka.com?fromDate=2009-08-30%2021:00'/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <entry>
        <atom:id>https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/domain/request ID</atom:id>
        <atom:updated>2009-04-17T15:29:21.064Z</atom:updated>
        <atom:link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/domain/request ID'/>
        <atom:link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/feeds/compliance/audit/mail/export/domain/request ID'/>
        <apps:property name='status' value='ERROR'/>
        <apps:property name='packageContent' value='FULL_MESSAGE'/>
        <apps:property name='includeDeleted' value='false'/>
        <apps:property name='searchQuery' value='in:chat'/>
        <apps:property name='completedDate' value='2009-09-18 10:13'/>
        <apps:property name='adminEmailAddress' value='[e-mail]'/>
        <apps:property name='numberOfFiles' value='0'/>
        <apps:property name='requestId' value='the mailbox ID for this request'/>
   </entry>
   <entry>
        <id>>https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/domain/second request ID</id>
        ...
        <apps:property name='status' value='COMPLETED'/>
        <apps:property name='packageContent' value='FULL_MESSAGE'/>
        <apps:property name='includeDeleted' value='false'/>
        <apps:property name='completedDate' value='2009-09-18 10:13'/>
        <apps:property name='adminEmailAddress' value='[e-mail]'/>
        <apps:property name='numberOfFiles' value='0'/>
        <apps:property name='requestId' value='the mailbox ID for this request'/>
        <apps:property name='userEmailAddress' value='[e-mail]'/>
        <apps:property name='endDate' value='2009-08-30 20:00'/>
        <apps:property name='requestDate' value='2009-09-17 12:51'/>
        <apps:property name='beginDate' value='2009-07-01 04:30'/>
   </entry>
</feed>

Java

import java.util.Calendar;
import java.util.List;
import com.google.gdata.client.appsforyourdomain.audit.AuditService;
import com.google.gdata.client.appsforyourdomain.audit.MailBoxDumpRequest;
import com.google.gdata.data.appsforyourdomain.generic.GenericEntry;
...

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
Calendar fromDate = Calendar.getInstance();
fromDate.set(2009, Calendar.AUGUST, 30, 21, 0);
List<GenericEntry> mailboxDumpRequestEntries = service.retrieveAllMailboxDumpRequests(fromDate.getTime());
for (GenericEntry entry : mailboxDumpRequestEntries) {
  MailBoxDumpRequest request = new MailBoxDumpRequest(entry);
  String status = request.getStatus();
}

.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("[e-mail]", "p@55w0rd");
GenericFeed<MailboxDumpRequest> dumpRequests = service.RetrieveAllMailboxDumpRequests(new DateTime(2009, 8, 30, 21, 0, 0);

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.

DELETE https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/{domain name}/{source user name}/{mailbox requestId}

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 [e-mail] corresponding to the requestId 34201.

Protocol

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

Java

import com.google.gdata.client.appsforyourdomain.audit.AuditService;
...

AuditService service = new AuditService("[e-mail]", "p@55w0rd", "example.com", "example.com-auditapp-v1");
service.deleteMailboxDumpRequest("liz", "34201");

.Net

using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...

AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("[e-mail]", "p@55w0rd");
service.DeleteMailboxDumpRequest("liz", "34201");