Zimbra Rest API | Zimbra

Zimbra displays its data through a REST API. REpresentational State Transfer (REST) is an approach used to build application services making resources accessible through a URL. You can learn more by reading this article Representational State Transfer from Wikipedia.

In this article we want to take a general overview of this functionality, analyzing its syntax and basic attributes.

Basic syntax

The basic syntax of Zimbra REST command is the following:

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

Where:

• protocol is the transport protocol, like for example http or https
• host is the hostname of Zimbra Server, for example “mail.yourdomain.com”
• user is the User. It can be specified in diffent ways:

http(s)://<host>/home/sample.user/{object}?{params}

if you want to use name.surname

http(s)://<host>/home/sample.user@yourdomain.com/{object}?{params}

if you are going to use the mail address sample.user@yourdomain.com

Another possibility is to use the “~” symbol to indicate the currently authenticated user

http(s)://<host>/home/~/{object}?{params}

• object denotes the object on which to execute the command. It can be a folder (e.g. inbox) or an item, and in this case the parameters of the query that is executed provide the information required by the command. Below a couple of examples:

http(s)://mail.yourdomain.com/home/sample.user/inbox.rss

If you want to download the inbox folder in RSS feed format. To download an item, you can write as follows:

http(s)://mail.yourdomain.com/home/sample.user/?id=123

• params is a list of command-specific URL parameters. We will look at this list in more detail in the description of each command.

Reply Formats

There are various kind of formats you can choose from for your response. To select the one you prefer you have to use the fmt= parameter in you command. Below we show you a list of formats available:

• xml – Extensible Markup Language
• json – JavaScript Object Notation
• rss – Really Simple Syndication web feed
• atom – Atom Syndication format
• html – HyperText Markup Language
• zip – Data compression and archive
• tar – Data archive
• tgz – Compressed tar file
• ics – iCalendar
• ifb – Internet Free Busy
• csv – Common Separated Value. Using csvfmt parameter you can select a specific CSV format (Zimbra, Yahoo, Thunderbird, Outlook)
• sync – this option is going to request the server to return additional meta-data in response headers.

Please note that if you don’t specify nohdr=1, the headers are returned inline of the reply.

Authentication

When accessing a mailbox there are several ways to login as a user. Through the use of the auth= parameter you can decide how to authenticate and whether or not to enable authentication cookies.

The default parameter is auth=co,nsc,qp where it first is going to check for a cookie auth token and then for query parameter auth token. At the end it will prompt for basic authentication. Below there is a list of comma-separated values supported by auth= parameter:

• co – In this case the authentication token will be retrieved from the ZM_AUTH_TOKEN cookie.
• qp – In this case the authentication token will be retrieved from request parameter zauthtoken.
• ba | nsc | sc – These are all related to basic authentication. In particular ba and nsc let you authenticate without setting cookie after it. sc will use basic authentication and set cookie.

Methods

REST API supports various methods to retrieve Zimbra data. You can find details about them in dedicated articles. To read them simply click the name of the method:

• Mail Methods
• Address Book Methods
• Calendar Methods
• Task Methods
• Item Methods
• Briefcase Methods
• Mailbox Methods

zmmailbox

A special mention deserves the CLI command zmmailbox, very useful to use with REST API. In fact, you can execute the rest methods through the command line. This is particularly useful in specific cases in which, for example, you decide to plan an import or export of particularly large mailboxes, where it is important to set the timeout to zero (infinite).

The syntax to export content via GET methods is the following:

zmmailbox -z -m user@yourdomain.com -t 0 getRestURL "/inbox?fmt=<format>"

To import content via POST, you can use the following syntax:

zmmailbox -z -m user@yourdomain.com -t 0 postRestURL "/inbox?fmt=<format>" /tmp/inbox.<format>