7.1 KiB

Raw Blame History

iRedAdmin-Pro: RESTful API

!!! note

If you need an API which has not yet been implemented, don't hesitate to
[contact us](../contact.html).

[TOC]

ChangeLog

May XX, 2016:
- NEW APIs:
  - /api/user/<mail>/password
  - /api/users/<domain>
  - /api/users/<domain>/password
- parameter used to update account profile preferredLanguage has been changed to language.
- API used to update user password is now: /api/user/<mail>/password (old is /api/user/<mail>)
May 3, 2016: initial publish.

Summary

iRedAdmin-Pro RESTful API will return message in JSON format.

If operation succeed, client will receive JSON data: {'success': true}.
If operation failed, client will receive JSON data: {'success': false, 'msg': '<error_reason>'}.

Requirements

RESTful API is available since iRedAdmin-Pro-SQL-2.4.0 and iRedAdmin-Pro-LDAP-2.6.0 (both released on May 3, 2016). Earlier releases didn't support RESTful API.

Enable RESTful API

RESTful API is disabled by default, to enable it, please add setting below in iRedAdmin-Pro config file settings.py:

ENABLE_RESTFUL_API = True

To restrict API access to few IP addresses, please also add settings below in iRedAdmin-Pro config file:

# Enable restriction
RESTRICT_API_ACCESS = True

# List all IP addresses of allowed client for API access.
RESTFUL_API_CLIENTS = ['172.16.244.1', ...]

Restarting Apache or uwsgi (if you're running Nginx) is required.

APIs

Notes:

replace <domain> in URL by the real domain name.
replace <mail> in URL by the real email address.

Domain

!!! api "/api/domain/<domain> POST Create a new domain" !!! api "/api/domain/<domain> DELETE Delete an existing domain" !!! api "/api/domain/<domain> PUT Update profile of an existing domain"

Possible `PUT` parameters used to update account profile:

Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | the short description of this domain name. e.g. company name | `cn=iRedMail Project`
`quota` | a integer number for mailbox quota (for whole domain, in MB) | `quota=20480`
`language` | default preferred language for new user | `language=en_US`
`defaultQuota` | default mailbox quota for new user | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a single mail user | `maxUserQuota=2048`
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`

User

!!! api "/api/user/<mail> POST Create a new mail user" !!! api "/api/user/<mail> DELETE Delete an existing mail user" !!! api "/api/user/<mail> PUT Update profile of an existing mail user" !!! api "/api/users/<domain> PUT Update profiles of all mail user under domain" !!! api "/api/users/<domain>/password PUT Update passwords of all users under domain"

Required parameter:
{: #param }

Parameter Name | Sample Usage
--- |---
`password` | `password=Ww0nXVEV8iv4ap@p4b`

URL	HTTP Method	Summary
/api/user/<mail>	POST	Create a new mail user
/api/user/<mail>	DELETE	Delete an existing mail user
/api/user/<mail>	PUT	Update profile of an existing mail user
/api/users/<domain>	PUT	Update profiles for all users under domain `<domain>`
/api/users/<domain>/password	PUT	Update passwords of all users under domain `<domain>`

Possible PUT parameters used to update account profile (/api/user/<mail>):

Parameter Name	Summary	Sample Usage
`cn`	display name	`cn=John Smith`
`accountStatus`	Account status	`accountStatus=disabled` (or `active`)
`language`	default preferred language for new user	`language=en_US`
`transport`	Transport program	`transport=dovecot`

Possible PUT parameters used to update profiles for all users under domain (/api/users/<domain>):

Parameter Name	Summary	Sample Usage
`accountStatus`	Account status	`accountStatus=disabled` (or `active`)
`language`	default preferred language for new user	`language=en_US`
`transport`	Transport program	`transport=dovecot`

Possible PUT parameters used to update passwords of all users under domain (/api/users/<domain>/password):

Parameter Name	Summary	Sample Usage
`password`	Update passwords of all users under domain	`password=Ww0nXVEV8iv4ap@p4b`

Mailing List

!!! note

This is applicable to OpenLDAP. For SQL backends, please use mail alias
account as mailing list.

URL	HTTP Method	Summary
/api/maillist/<mail>	POST	Create a new mailing list
/api/maillist/<mail>	DELETE	Delete an existing mailing list
/api/maillist/<mail>	PUT	Update profile of an existing mailing list

Possible PUT parameters used to update account profile:

Parameter Name	Summary	Sample Usage
`cn`	display name	`cn=My List Name`
`accessPolicy`	Defines who can send email to this mailing list	`accessPolicy=public`

Mail Alias

URL	HTTP Method	Summary
/api/alias/<mail>	POST	Create a new mail alias
/api/alias/<mail>	DELETE	Delete an existing mail alias
/api/alias/<mail>	PUT	Update profile of an existing mail alias