Zimbra REST API Reference: Difference between revisions

No edit summary
(Remove old ZCS_6.0 prefixes)
 
(71 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Zimbra exposes its data via a REST API. This document is the reference for that functionality.
{{Template:TabHeader}}
{{Template:Tab1|[[Zimbra_REST_API_Reference|Introduction]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Folder|Method: Get Folder]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Import_Message|Method: Import Message]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Contacts|Method: Get Contacts]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Import_Contacts|Method: Import Contacts]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Calendar|Method: Get Calendar]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_FreeBusy|Method: Get FreeBusy]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Import_Appointments|Method: Import Appointments]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Tasks|Method: Get Tasks]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Item|Method: Get Item]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Briefcase|Method: Get Briefcase]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Get_Briefcase_Item|Method: Get Briefcase Item]]}}
{{Template:Tab2|[[Zimbra_REST_API_Reference:Export_Mailbox|Method: Export Mailbox]]}}
{{Template:TabFooter}}
 
{{Article Infobox|{{devel}}|{{ZCS 8.0}}|{{ZCS 7.0}}|{{ZCS 6.0}}|}}Zimbra exposes its data via a REST API. This document is the reference for that functionality.


REST (REpresentational State Transfer) is an approach for building application services that make resources available via a URL. For example, the following REST command retrieves all inbox items as a simple RSS feed:
REST (REpresentational State Transfer) is an approach for building application services that make resources available via a URL. For example, the following REST command retrieves all inbox items as a simple RSS feed:
Line 19: Line 35:
</pre>
</pre>


The following describes the components of the REST command:
HTTP <code>GET</code> methods are for reading items. HTTP <code>POST</code> methods are for creating/modifying items. The following describes the components of the Zimbra REST command:


{|cellpadding="5" cellspacing="0" border="1" width="100%"
{|cellpadding="5" cellspacing="0" border="1" width="100%"
Line 47: Line 63:
</pre>
</pre>
</ul>
</ul>
You can also use "~" as a shortcut to the current user. For example:
You can also use "~" as a shortcut to the current authenticated user. For example:
<pre>
<pre>
http://localhost:7070/home/~/inbox.rss
http://localhost:7070/home/~/inbox.rss
Line 53: Line 69:
|-
|-
|<code>object</code>
|<code>object</code>
|Designates the object to perform the command against. This might be a folder (such as inbox or drafts) or omitted (to download a specific item). If omitted, the query parameters will provide the information the command requires.
|Designates the object to perform the command against. This might be a folder (such as inbox or drafts) or omitted (to download a specific item). If omitted, the query parameters provide the information the command requires.


For example, to download the inbox folder as XML:
For example, to download the inbox folder as XML:
Line 72: Line 88:
=== Response Formats ===
=== Response Formats ===


XYZ
The following describes the various response formats, designated using the <code>fmt=</code> parameter. Not all commands support all formats. See the specific command for a list of supported formats and command-specific details:
 
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|style="background-color:#ffffcc;" width="15%"|'''Format'''
|style="background-color:#ffffcc;"|'''Description'''
|-
|<code>xml</code>
|Extensible Markup Language file format. See the Wikipedia article [http://en.wikipedia.org/wiki/XML http://en.wikipedia.org/wiki/XML]
|-
|<code>json</code>
|JavaScript Object Notation file format. See [http://www.json.org http://www.json.org]
|-
|<code>rss</code>
|Really Simple Syndication web feed format. See [http://en.wikipedia.org/wiki/RSS http://en.wikipedia.org/wiki/RSS]
|-
|<code>atom</code>
|Atom syndication format. See [http://en.wikipedia.org/wiki/Atom_(standard)]
|-
|<code>html</code>
|Hyper Text Markup Language file format. Produced the output as a web page.
|-
|<code>zip</code>
|Data compression and archive format.
|-
|<code>tar</code>
|Data archive format ("tar").
|-
|<code>tgz</code>
|Compressed <code>tar</code> file.
|-
|<code>ics</code>
|iCalendar file format. See [http://en.wikipedia.org/wiki/ICalendar http://en.wikipedia.org/wiki/ICalendar] and [http://tools.ietf.org/html/rfc2445 RFC 2445].
|-
|<code>ifb</code>
|Internet Free Busy format. See [http://tools.ietf.org/html/rfc2445 RFC 2445].
|-
|<code>csv</code>
|Common Separated Values file format. A specific CSV format can be designated using the <code>csvfmt</code> parameter. Supported CSV formats include:
<ul>
<li>zimbra-csv</li>
<li>yahoo-csv</li>
<li>thunderbird-csv</li>
<li>outlook-2000-csv</li>
<li>outlook-2003-csv</li>
</ul>
|-
|<code>sync</code>
|Requests that the server return additional meta-data in the response headers. When using this option, the headers are returned inline of the response, unless you specify <code>nohdr=1</code>.
 
For example, get a mail message by item id and return the meta-data in the response headers and inline.
<pre>
http://localhost:7070/home/john.doe/?id=288&fmt=sync
</pre>
 
For example, get a mail message by item id and return the meta-data in the response headers only.
<pre>
http://localhost:7070/home/john.doe/?id=288&fmt=sync&nohdr=1
</pre>
 
The following is a list of the meta-data headers:
<ul>
<li>X-Zimbra-ItemId</li>
<li>X-Zimbra-FolderId</li>
<li>X-Zimbra-Tags</li>
<li>X-Zimbra-Flags</li>
<li>X-Zimbra-Received</li>
<li>X-Zimbra-Modified</li>
<li>X-Zimbra-Change</li>
<li>X-Zimbra-Revision</li>
<li>X-Zimbra-Conv</li>
</ul>
 
|}


=== Authentication ===
=== Authentication ===


XYZ
There are multiple methods to authenticate as a user when accessing a mailbox. Using the <code>auth=</code> parameter, you can designate how to authenticate and whether or not to set the authentication cookie.
 
Default is <code>auth=co,nsc,qp</code>. Meaning: first, check for a cookie auth token; second, check for query parameter auth token; thrid, prompt for basic authentication.
 
The <code>auth=</code> parameter supports a list of comma-separated values which include:
 
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|style="background-color:#ffffcc;" width="10%"|'''Value'''
|style="background-color:#ffffcc;"|'''Description'''
|-
|<code>co</code>
|The authentication token will be retrieved from the <code>ZM_AUTH_TOKEN</code> cookie.
For example:
<pre>
http://localhost:7070/home/john.doe/inbox.rss?auth=co
</pre>
|-
|<code>qp</code>
|The authentication token will be retrieved from request parameter <code>zauthtoken</code>.
For example:
<pre>
http://localhost:7070/home/john.doe/inbox.rss?auth=qp&zauthtoken=0_thisismyzauthtokenthisismyzauthtoken_thisismyzauthtoken
</pre>
|-
|
<code>ba</code>
<br>
<code>nsc</code>
<br>
<code>sc</code>
|These methods refer to Basic Authentication:
<ul>
<li><code>ba</code> = Use Basic Authentication and do not set cookie after authentication.</li>
<li><code>nsc</code> = Same as <code>ba</code>.</li>
<li><code>sc</code> = Use Basic Authentication and set cookie after authentication.</li>
</ul>
For example:
<pre>
http://localhost:7070/home/john.doe/inbox.rss?auth=ba
</pre>
|}


== Methods ==
== Methods ==
Line 82: Line 210:
The API supports the following methods to retrieve Zimbra data.
The API supports the following methods to retrieve Zimbra data.


=== Folder Methods ===
=== Mail Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Folder|Get Folder]]
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Import_Message|Import Message]]
 
=== Address Book Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Contacts|Get Contacts]]
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Import_Contacts|Import Contacts]]
 
=== Calendar Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Calendar|Get Calendar]]
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_FreeBusy|Get FreeBusy]]
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Import_Appointments|Import Appointments]]
 
=== Task Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Tasks|Get Tasks]]
 
=== Item Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Item|Get Item]]
 
=== Briefcase Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Briefcase|Get Briefcase]]
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Briefcase_Item|Get Briefcase Item]]
 
=== Mailbox Methods ===
 
[[ZCS_6.0:Zimbra_REST_API_Reference:Export_Mailbox|Export Mailbox]]
 
== Using the zmmailbox CLI ==
 
A useful Zimbra Command Line Interface (CLI) for use with the REST API is <code>zmmailbox</code>. With <code>zmmailbox</code>, you can execute REST methods via the command line. This is a particularly useful tool if you plan to script exporting & importing data. See the [http://www.zimbrablog.com/blog/archives/2008/09/zcs-to-zcs-migrations.html ZCS-to-ZCS Migrations] blog entry for an example. When exporting/importing large mailboxes, it is important to set the timeout to "0" (infinity):
 
To perform <code>GET</code> methods (like exporting the inbox content in ZIP format), use the following syntax:
 
<pre>
zmmailbox -z -m user@domain.com -t 0 getRestURL "/inbox?fmt=zip"
</pre>
 
To perform <code>POST</code> methods (like importing the content of inbox.zip), use the following syntax:
 
<pre>
zmmailbox -z -m user@domain.com -t 0 postRestURL "/inbox?fmt=zip" /tmp/inbox.zip
</pre>


[[ZCS_6.0:Zimbra_REST_API_Reference:Get_Inbox|Get Inbox]]


[[ZCS_6.0:Zimbra REST API Reference:Get_Drafts|Get Drafts]]


[[ZCS_6.0:Zimbra REST API Reference:Get_Sent|Get Sent]]
{{Article Footer|Zimbra Collaboration Server 7.0|01/16/2010}}


[[ZCS_6.0:Zimbra REST API Reference:Get_Trash|Get Trash]]


[[ZCS_6.0:Zimbra REST API Reference:Get_Folder|Get Folder]]
[[Category:REST]]
[[Category:ZCS 7.0]]
[[Category:ZCS 6.0]]
[[Category:Developers]]

Latest revision as of 17:19, 5 August 2014

Introduction  


Method: Get Folder  


Method: Import Message  


Method: Get Contacts  


Method: Import Contacts  


Method: Get Calendar  


Method: Get FreeBusy  


Method: Import Appointments  


Method: Get Tasks  


Method: Get Item  


Method: Get Briefcase  


Method: Get Briefcase Item  


Method: Export Mailbox  


 


Developer Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.0 Article ZCS 8.0 ZCS 7.0 Article ZCS 7.0 ZCS 6.0 Article ZCS 6.0

Zimbra exposes its data via a REST API. This document is the reference for that functionality.

REST (REpresentational State Transfer) is an approach for building application services that make resources available via a URL. For example, the following REST command retrieves all inbox items as a simple RSS feed: 

http://localhost:7070/home/user1/inbox.rss

Learn more about REST at the Wikipedia article Representational State Transfer.

Overview

Command Format

The format of a Zimbra REST command is: 

{protocol}://{host}:{port}/home/{user}/{object}?{params}

HTTP GET methods are for reading items. HTTP POST methods are for creating/modifying items. The following describes the components of the Zimbra REST command:

Component Description
protocol The transport protocol, for example, http.
host The host name or IP address of the Zimbra Collaboration Suite server
port The port number, for example, 7070.
user The user. To load an explicit user account, specify the user in one of the following formats:
  • john.doe 
    http://localhost:7070/home/john.doe/inbox.rss
  • john.doe@mydomain.com
    • http://localhost:7070/home/john.doe@mydomain.com/inbox.rss

You can also use "~" as a shortcut to the current authenticated user. For example: 

http://localhost:7070/home/~/inbox.rss
object Designates the object to perform the command against. This might be a folder (such as inbox or drafts) or omitted (to download a specific item). If omitted, the query parameters provide the information the command requires.

For example, to download the inbox folder as XML: 

http://localhost:7070/home/john.doe/inbox.rss

For example, to download an item: 

http://localhost:7070/home/john.doe/?id=657
params A list of command-specific URL parameters. See the specific command for a list of the required and optional parameters.

Response Formats

The following describes the various response formats, designated using the fmt= parameter. Not all commands support all formats. See the specific command for a list of supported formats and command-specific details:

Format Description
xml Extensible Markup Language file format. See the Wikipedia article http://en.wikipedia.org/wiki/XML
json JavaScript Object Notation file format. See http://www.json.org
rss Really Simple Syndication web feed format. See http://en.wikipedia.org/wiki/RSS
atom Atom syndication format. See [1]
html Hyper Text Markup Language file format. Produced the output as a web page.
zip Data compression and archive format.
tar Data archive format ("tar").
tgz Compressed tar file.
ics iCalendar file format. See http://en.wikipedia.org/wiki/ICalendar and RFC 2445.
ifb Internet Free Busy format. See RFC 2445.
csv Common Separated Values file format. A specific CSV format can be designated using the csvfmt parameter. Supported CSV formats include:
  • zimbra-csv
  • yahoo-csv
  • thunderbird-csv
  • outlook-2000-csv
  • outlook-2003-csv
sync Requests that the server return additional meta-data in the response headers. When using this option, the headers are returned inline of the response, unless you specify nohdr=1.

For example, get a mail message by item id and return the meta-data in the response headers and inline. 

http://localhost:7070/home/john.doe/?id=288&fmt=sync

For example, get a mail message by item id and return the meta-data in the response headers only. 

http://localhost:7070/home/john.doe/?id=288&fmt=sync&nohdr=1

The following is a list of the meta-data headers:

  • X-Zimbra-ItemId
  • X-Zimbra-FolderId
  • X-Zimbra-Tags
  • X-Zimbra-Flags
  • X-Zimbra-Received
  • X-Zimbra-Modified
  • X-Zimbra-Change
  • X-Zimbra-Revision
  • X-Zimbra-Conv

Authentication

There are multiple methods to authenticate as a user when accessing a mailbox. Using the auth= parameter, you can designate how to authenticate and whether or not to set the authentication cookie.

Default is auth=co,nsc,qp. Meaning: first, check for a cookie auth token; second, check for query parameter auth token; thrid, prompt for basic authentication.

The auth= parameter supports a list of comma-separated values which include:

Value Description
co The authentication token will be retrieved from the ZM_AUTH_TOKEN cookie.

For example: 

http://localhost:7070/home/john.doe/inbox.rss?auth=co
qp The authentication token will be retrieved from request parameter zauthtoken.

For example: 

http://localhost:7070/home/john.doe/inbox.rss?auth=qp&zauthtoken=0_thisismyzauthtokenthisismyzauthtoken_thisismyzauthtoken

ba
nsc
sc

These methods refer to Basic Authentication:
  • ba = Use Basic Authentication and do not set cookie after authentication.
  • nsc = Same as ba.
  • sc = Use Basic Authentication and set cookie after authentication.

For example: 

http://localhost:7070/home/john.doe/inbox.rss?auth=ba

Methods

The API supports the following methods to retrieve Zimbra data.

Mail Methods

Get Folder

Import Message

Address Book Methods

Get Contacts

Import Contacts

Calendar Methods

Get Calendar

Get FreeBusy

Import Appointments

Task Methods

Get Tasks

Item Methods

Get Item

Briefcase Methods

Get Briefcase

Get Briefcase Item

Mailbox Methods

Export Mailbox

Using the zmmailbox CLI

A useful Zimbra Command Line Interface (CLI) for use with the REST API is zmmailbox. With zmmailbox, you can execute REST methods via the command line. This is a particularly useful tool if you plan to script exporting & importing data. See the ZCS-to-ZCS Migrations blog entry for an example. When exporting/importing large mailboxes, it is important to set the timeout to "0" (infinity):

To perform GET methods (like exporting the inbox content in ZIP format), use the following syntax: 

zmmailbox -z -m user@domain.com -t 0 getRestURL "/inbox?fmt=zip"

To perform POST methods (like importing the content of inbox.zip), use the following syntax: 

zmmailbox -z -m user@domain.com -t 0 postRestURL "/inbox?fmt=zip" /tmp/inbox.zip


Verified Against: Zimbra Collaboration Server 7.0 Date Created: 01/16/2010
Article ID: https://wiki.zimbra.com/index.php?title=Zimbra_REST_API_Reference Date Modified: 2014-08-05



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Other help Resources

User Help Page »
Official Forums »
Zimbra Documentation Page »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Retrieved from "http://wiki.zimbra.com/index.php?title=Zimbra_REST_API_Reference&oldid=55313"
Jump to: navigation, search