For additional guidance, check out our community articles detailing the process of migrating from your current platform to Carbonio CE.
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 examplehttp
orhttps
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
andnsc
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>