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.
The basic syntax of Zimbra REST command is the following:
protocolis the transport protocol, like for example
hostis the hostname of Zimbra Server, for example “mail.yourdomain.com”
useris the User. It can be specified in diffent ways:
if you want to use name.surname
if you are going to use the mail address firstname.lastname@example.org
Another possibility is to use the “~” symbol to indicate the currently authenticated user
- 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:
If you want to download the inbox folder in RSS feed format. To download an item, you can write as follows:
paramsis a list of command-specific URL parameters. We will look at this list in more detail in the description of each command.
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
- 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.
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
- co – In this case the authentication token will be retrieved from the
- qp – In this case the authentication token will be retrieved from request parameter
- ba | nsc | sc – These are all related to basic authentication. In particular
nsclet you authenticate without setting cookie after it.
scwill use basic authentication and set cookie.
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
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 email@example.com -t 0 getRestURL "/inbox?fmt=<format>"
To import content via
POST, you can use the following syntax:
zmmailbox -z -m firstname.lastname@example.org -t 0 postRestURL "/inbox?fmt=<format>" /tmp/inbox.<format>