Zimbra REST API Reference: Difference between revisions
No edit summary |
|||
Line 250: | Line 250: | ||
== Using the zmmailbox CLI == | == 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. | 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: | To perform <code>GET</code> methods (like exporting the inbox content in ZIP format), use the following syntax: | ||
<pre> | <pre> | ||
zmmailbox -z -m user@domain.com getRestURL "/inbox?fmt=zip" | zmmailbox -z -m user@domain.com -t 0 getRestURL "/inbox?fmt=zip" | ||
</pre> | </pre> | ||
Line 261: | Line 261: | ||
<pre> | <pre> | ||
zmmailbox -z -m user@domain.com postRestURL "/inbox?fmt=zip" /tmp/inbox.zip | zmmailbox -z -m user@domain.com -t 0 postRestURL "/inbox?fmt=zip" /tmp/inbox.zip | ||
</pre> | </pre> | ||
Revision as of 21:41, 5 March 2014
Article Information |
---|
This article applies to the following ZCS versions. |
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:
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:
|
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:
|
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 |
|
These methods refer to Basic 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
Address Book Methods
Calendar Methods
Task Methods
Item Methods
Briefcase Methods
Mailbox Methods
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