The Google Workspace Email Audit API allows Google Workspace administrators to audit a user's email, email drafts, and archived Hangouts 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 Google Workspace, Education, and ISPs accounts. It is not used with a Google Workspace or Gmail account not hosted by the Google Workspace products.
The Google Workspace 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 Google Workspace user's mailbox.
This document assumes that you are a Google Workspace domain administrator
and that you understand the general ideas behind the
Google Data API protocol, and that you are familiar
with your Google Workspace Admin console found at
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 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 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 theexample.com
domain, to makenamrata@example.com
the destination user, usename='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, theendDate
property's value must be greater than the current date. :- The date format is
yyyy-MM-dd HH:mm
where theHH
is the hour of the day using 0 - 23, and themm
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.
- The date format is
- endDate
- The
endDate
is the date when the audit stops. This is a required element. :- Using the same syntax as the
beginDate
parameter, theendDate
format isyyyy-MM-dd HH:mm
where theHH
is the hour of the day using 0 - 23, and themm
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 yourbeginDate
property's value. If thebeginDate
is not specified, the current date becomes thebeginDate
property's value. In this case, theendDate
must be greater than the current date.
- Using the same syntax as the
- 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 isFULL_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 isFULL_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 Hangouts 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.
Example for creating a new monitor
In this example:
- The user to be audited is
abhishek@example.com
. - 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("admin@example.com", "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("admin@example.com", "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
abhishek@example.com
. - The destUserName remains
namrata
.
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("admin@example.com", "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("admin@example.com", "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 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
).
<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("admin@example.com", "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("admin@example.com", "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}
Example for deleting an email monitor
This example deletes the monitors created for the user abhishek@example.com
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("admin@example.com", "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("admin@example.com", "p@55w0rd"); service.DeleteMailMonitor("abhishek", "namrata");
Accessing Account Information
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 usinggpg --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.
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 theHH
is the hour of the day using 0 - 23, and themm
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.
- The date format is
- endDate
- The
endDate
is the date for the last email included in the exported mailbox. This is an optional element. If theendDate
is not specified or an empty string, the exported emails go up to the current date. :- Using the same syntax as the
beginDate
parameter, theendDate
format isyyyy-MM-dd HH:mm
where theHH
is the hour of the day using 0 - 23, and themm
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 yourbeginDate
property's value.
- Using the same syntax as the
- 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
andincludeDeleted
parameters are mutually exclusive. A search query is not possible ifincludeDeleted = "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.
- FULL_MESSAGE — The full email text, including attachments, is copied to the export file. This is the default setting for the
Example for creating a mailbox for export
We'll use the following settings in this example:
- The user to export the mailbox for is
liz@example.com
. - 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='admin1@example.com'/> <apps:property name='requestId' value='53156'/> <apps:property name='userEmailAddress' value='liz@example.com'/> <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("admin@example.com"); request.setUserEmailAddress("liz@example.com"); 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("admin@example.com", "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("admin@example.com", "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.
Example for retrieving the export status of a mailbox
This example retrieves the mailbox status corresponding to the requestIds <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='admin1@example.com'/>
<apps:property name='numberOfFiles' value='0'/>
<apps:property name='requestId' value='53156'/>
<apps:property name='userEmailAddress' value='liz@example.com'/>
<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 As you can see from the response of the example above, the status is an We'll try again for the <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='admin2@example.com'/>
<apps:property name='numberOfFiles' value='2'/>
<apps:property name='requestId' value='34201'/>
<apps:property name='userEmailAddress' value='namrata@example.com'/>
<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 AuditService service = new AuditService("admin@example.com", "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");
AuditService service = new AuditService("example.com", "example.com-auditapp-v1");
service.setUserCredentials("admin@example.com", "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;
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
201 CREATED
status code found in the Google Data API HTTP status codes documentation.ERROR
and, therefore, the encrypted mailbox files were never created.requestId
34201
:
GET https://apps-apis.google.com/a/feeds/compliance/audit/mail/export/example.com/liz/34201
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;
...
.NET
using System;
using Google.GData.Apps;
using Google.GData.Extensions.Apps;
...
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}
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='admin1@example.com'/> <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='admin1@example.com'/> <apps:property name='numberOfFiles' value='0'/> <apps:property name='requestId' value='the mailbox ID for this request'/> <apps:property name='userEmailAddress' value='liz@example.com'/> <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("admin@example.com", "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("admin@example.com", "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}
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
.
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("admin@example.com", "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("admin@example.com", "p@55w0rd"); service.DeleteMailboxDumpRequest("liz", "34201");