ZimbraRestApi

This is a REST Proxy to the Zimbra SOAP API. In other words it make possible to do this:

$ curl 'http://localhost:9292/accounts/?domain=example.com' | \
  jq '[.[] | { email: .name, name: .zimbra_attrs.givenName, lastname: .zimbra_attrs.sn, aliases: .zimbra_attrs.zimbraMailAlias}] '

Note: The example uses jq, a command-line JSON processor

You get JSON as result. Why is this great? Because JSON is structured data that you can operate.

{
    "email": "jpugenin@example.com",
    "name": "Juan",
    "lastname": "Pugenin",
    "aliases": [
      "juan@example.com",
      "j.pugenin@example.com",
    ]
  },
  {
    "email": "krriagada@example.com",
    "name": "Karen",
    "lastname": "Riagada",
    "aliases": [
      "karen@example.com",
      "karen@zboxapp.com",
    ]
  },

Documentation

Only tested with Ruby version 2 or greater

Standalone Installation

Just clone the repo and run bundle

$ git clone https://github.com/ZBoxApp/zimbra-rest-api.git
$ cd zimbra-rest-api
$ bundle

Usage

Enviroment Variables

This Gem expects the following ENV Variables to work properly:

zimbra_soap_url: 'https://ZIMBRA_SERVER:7071/service/admin/soap',
zimbra_admin_user: Admin user email to use,
zimbra_admin_password: The password of the admin user

The following are optional, and you can past a list separated by ','

zimbra_account_attrs: Account attributes to load when doing a search
zimbra_domain_attrs: Domain attributes to load when doing a search
zimbra_dl_attrs: DistributionList attributes to load when doing a search

Running the server

This example export the ENV variables and then run the server

$ export zimbra_soap_url=https://127.0.0.1:7071/service/admin/soap
$ export zimbra_admin_user=admin@zboxapp.dev
$ export zimbra_admin_password=12345678
$ export zimbra_account_attrs='sn,givenName,displayName,zimbraMailAlias'

Now Run the server:

$ bundle exec rackup
------------------------------------------------
Starting server with the following configuration
SOAP URL: https://127.0.0.1:7071/service/admin/soap
ADMIN USER: admin@zboxapp.dev
------------------------------------------------
[2016-02-26 13:11:48] INFO  WEBrick 1.3.1
[2016-02-26 13:11:48] INFO  ruby 2.0.0 (2013-05-14) [x86_64-darwin12.3.0]
[2016-02-26 13:11:48] INFO  WEBrick::HTTPServer#start: pid=52894 port=9292

And now you can query it at port 9292.

REST Routes

You have the following routes: /accounts/, /domains/ and /distribution_lists/. For all of them you have the same actions:

POST: For create
GET: Without ID returns all the objects, with an ID return the requested object
PUT: For update
DELETE: For... yes, delete

Some examples:

 # Create a new Account
 $ curl -X POST -d "name='tmp@zbox.cl', password='12345678', displayName='tmp user'" http://localhost:9292/accounts/

 # Get All Domains
 $ curl http://localhost:9292/domains/

 # Get Domain using the name zboxapp.com
 $ curl http://localhost:9292/domains/zboxapp.com/

 # get Distribuition List using the zimbraId
 $ curl http://localhost:9292/distribution_lists/79a627c7-0ead-4cd3-b809-1e1f71ef373d/

 # Delete an Account using the zimbraId
 $ curl -X DELETE http://localhost:9292/accounts/c3525317-7172-420a-8d78-7f5ce1d195e5/

 # Update an Account
 $ curl -X PUT -d "'displayName'='Patricio Bruna'" http://localhost:9292/accounts/pbruna@zboxapp.com/

Searching

By default if you make a GET request without an ID, the server makes a DirectorySearch, so you can pass query params, like:

 # Search all Admins Accounts
 $ curl -X GET -d 'zimbraIsAdminAccount='TRUE'' http://localhost:9292/accounts/

 # Search all Distribuition List for a given Domain
 $ curl -X GET -d 'domain=example.com' http://localhost:9292/distribution_lists/

 # Search with a RAW LDAP Filter
 $ export ldap_filter = '(&(|(zimbraMailDeliveryAddress=*@customer1.dev))(!(zimbraIsSystemAccount=TRUE)))'
 $ curl -X GET -d "raw_ldap_filter=$ldap_filter" http://localhost:9292/distribution_lists/

Special Requests

Count Accounts by Domain

Return the accounts grouped by COS for a given domain:

$ curl http://localhost:9292/domains/example.com/count_accounts
{"0bdd20b6-9fca-4f3c-a0e3-b8aa045c2ae0":3,"0ae7404d-4851-5ea4-a2d5-620a19b32b72":9}

Add Domain Accounts Limits

Limit the amount of accounts a Domain can have, in total and by COS

 # 20 accounts for the COS with ID 0bdd20b6-9fca-4f3c-a0e3-b8aa045c2ae0
 $ limit_by_cos = "0bdd20b6-9fca-4f3c-a0e3-b8aa045c2ae0:20"
 $ curl -X POST -d "total=30, cos=$limit_by_cos" http://localhost:9292/domains/example.com/accounts_quota

Account Mailbox Info

Storage (in bytes) and ID of the account mailbox:

$ curl http://localhost:9292/accounts/pbruna@example.com/mailbox
{"size":14755669972,"store_id":4640}

Add and Remove Account Alias

 # Add alias
 $ curl -X POST -d 'alias_name="pato@example.com"' http://localhost:9292/accounts/pbruna@example.com/add_alias

 # Remove alias
 $ curl -X POST -d 'alias_name="pato@example.com"' http://localhost:9292/accounts/pbruna@example.com/remove_alias

Token for view other account webmail

$ curl http://localhost:9292/accounts/pbruna@example.com/delegated_token
{"delegated_token":"0_9eca5cf3ec47480c1a216d9978d42e89b76fecab_69643d33363a63666436653931342d346630302d343430632d396135372d6531613933323731323862393b6578703d31333a313435363530393237333033393b6169643d33363a63666436653931342d346630302d343430632d396135372d6531613933323731323862393b76763d323a31373b747970653d363a7a696d6272613b7469643d31303a313930303734343336343b76657273696f6e3d31333a382e362e305f47415f313135333b"}

Account Archiving (Only Zimbra Network)

This let you enable the mail archiving. If the archiving mailbox doest not exists, it creates it. You always must pass the Archiving COS ID

 # Enable archiving
 $ curl -X POST -d 'cos_id=cos_id' "/accounts/pbruna@example.com/archive/enable"

 # Disable archiving
 $ curl -X POST "/accounts/pbruna@example.com/archive/disable"

Disabling does not delete the archiving mailbox, only disable further mail archiving.

Account Distribution List Memberships

Get a list of DLs to which an account belongs to. The via attribute indicates if the account belongs to other DL that belongs to this DL.

$ curl http://localhost:9292/accounts/pbruna@example.com/memberships | jq '.'
[
  {
    "id": "0253aa7e-7f05-4a15-88a2-4e1493fa5ce3",
    "name": "alertas@example.com",
    "via": null
  },
  {
    "id": "fe968179-5868-4fe1-a765-0c2d9431f328",
    "name": "comercial@example.com",
    "via": null
  },
  {
    "id": "baab2e9f-0ce3-41db-8643-ac0a7567a582",
    "name": "consultas@example.com",
    "via": null
  },
  {
    "id": "53506b58-ea1b-4f61-a8ff-c5fd61b14aca",
    "name": "devops@example.com",
    "via": 'alertas@example.com'
  }...

Add and Remove Members to Distribution Lists

 # Add members
 post "/distribution_lists/sales@example.com/add_members", {'members' => ['pp@gmail.com', 'pa@gmail.com']}

 # Remove members
 post "/distribution_lists/sales@example.com/remove_members", {'members' => ['pbruna@gmail.com']}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Fork it ( https://github.com/[my-github-username]/zimbra_rest_api/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

zimbra-rest-api

Development

Runtime

ZimbraRestApi

Documentation

Standalone Installation

Usage

Enviroment Variables

Running the server

REST Routes

Searching

Special Requests

Count Accounts by Domain

Add Domain Accounts Limits

Account Mailbox Info

Add and Remove Account Alias

Token for view other account webmail

Account Archiving (Only Zimbra Network)

Account Distribution List Memberships

Add and Remove Members to Distribution Lists

Development

Contributing