2016-04-18 09:34:43 -05:00
# iRedAdmin-Pro: RESTful API
!!! note
If you need an API which has not yet been implemented, don't hesitate to
[contact us ](../contact.html ).
2016-04-20 05:23:37 -05:00
[TOC]
2016-06-06 10:29:23 -05:00
### ChangeLog
* Variable names in returned JSON data has been changed to:
`{'_success': ..., '_msg': ...}` (was `{'success': ..., 'msg': ...}` ).
2016-06-24 22:39:58 -05:00
* Some variable names have been renamed:
* `cn` -> `name` .
* `mailQuota` -> `quota`
2016-09-17 23:41:54 -05:00
* `preferredLanguage` -> `language`
2016-06-06 10:29:23 -05:00
2016-04-18 09:34:43 -05:00
## Summary
iRedAdmin-Pro RESTful API will return message in JSON format.
2016-08-02 02:56:26 -05:00
* If operation succeed:
* For `POST` , `DELETE` , `PUT` actions, it returns JSON data: `{'_success': true}` .
* For `GET` action, it returns JSON data: `{'_success': true, '_data': <program_output>}` .
* If operation failed, it returns JSON data: `{'_success': false, '_msg': '<error_reason>'}` .
2016-04-18 09:34:43 -05:00
## Requirements
* At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases
didn't offer RESTful API.
2016-04-21 10:42:39 -05:00
## 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.
2016-05-14 11:18:14 -05:00
## Sample code to interact with iRedAdmin-Pro RESTful API
* [iRedAdmin-Pro RESTful API (interact with `curl`) ](./iredadmin-pro.restful.api.curl.html )
* [iRedAdmin-Pro RESTful API (interact with Python) ](./iredadmin-pro.restful.api.python.html )
2016-04-18 09:34:43 -05:00
## APIs
Notes:
2016-05-14 11:18:14 -05:00
* Parameter name with a `*` mark means the parameter is required, otherwise is optional.
2016-04-18 09:34:43 -05:00
* replace `<domain>` in URL by the real domain name.
* replace `<mail>` in URL by the real email address.
2016-05-14 11:18:14 -05:00
< button type = "button" class = "toggle_all" > Expand/Collapse All API Parameters< / button >
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
### Domain {: .toggle }
2016-04-18 09:34:43 -05:00
2016-10-09 00:35:28 -05:00
!!! api "`GET`{: .get } `/api/domain/<domain>` {: .url } `Get profile of an existing domain` {: .comment } `upcoming` {: .upcoming }"
2016-05-14 11:18:14 -05:00
!!! api "`POST`{: .post } `/api/domain/<domain>` {: .url } `Create a new domain` {: .comment } `Parameters` {: .has_params }"
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
< div class = "params params_domain" >
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-06-01 10:38:58 -05:00
`name` | Short description of this domain name. e.g. company name | `name=Google Inc`
2016-05-19 06:41:31 -05:00
`quota` | Per-domain mailbox quota, in MB. | `quota=2048`
2016-05-23 19:40:23 -05:00
`language` | Default preferred language for newly created mail user | `language=en_US`
2016-06-01 10:38:58 -05:00
`transport` | Transport program | `transport=dovecot`
2016-05-19 06:41:31 -05:00
`defaultQuota` | Default per-user mailbox quota for newly created user, in MB. | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a mail user, in MB. | `maxUserQuota=2048`
2016-05-14 11:18:14 -05:00
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`
2016-10-10 11:12:16 -05:00
`numberOfLists` | Max number of mailing list accounts (Available in LDAP backends)| `numberOfLists=40`
2016-06-01 10:38:58 -05:00
`senderBcc` | Per-domain sender bcc | `senderBcc=user@domain.com`
`recipientBcc` | Per-domain recipient bcc | `recipientBcc=user@domain.com`
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
< / div >
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
!!! api "`DELETE`{: .delete } `/api/domain/<domain>` {: .url } `Delete an existing domain` {: .comment }"
2016-06-01 10:38:58 -05:00
!!! api "`PUT`{: .put } `/api/domain/<domain>` {: .url } `Update profile of an existing domain` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params }"
2016-04-18 09:34:43 -05:00
2016-05-14 11:18:14 -05:00
< div class = "params params_domain" >
2016-04-20 02:11:50 -05:00
2016-05-14 11:18:14 -05:00
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-06-01 10:38:58 -05:00
`name` | Short description of this domain name. e.g. company name | `name=Google Inc`
2016-10-09 01:06:35 -05:00
`accountStatus` | Enable or disable domain. Possible values: `active` , `disabled` . | `accountStatus=active`
2016-05-14 11:18:14 -05:00
`quota` | Mailbox quota for whole domain, in MB. | `quota=2048`
2016-06-01 10:38:58 -05:00
`language` | Default preferred language for newly created mail user | `language=en_US`
2016-05-25 04:50:06 -05:00
`transport` | Transport program | `transport=dovecot`
2016-11-15 21:18:01 -06:00
`minPasswordLength` | Minimal password length | `minPasswordLength=8`
`maxPasswordLength` | Maximum password length | `minPasswordLength=20`
2016-05-25 04:50:06 -05:00
`defaultQuota` | Default per-user mailbox quota for newly created user | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a mail user | `maxUserQuota=2048`
2016-06-01 10:38:58 -05:00
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`
2016-06-06 10:29:23 -05:00
`senderBcc` | Per-domain sender bcc address | `senderBcc=user@domain.com`
`recipientBcc` | Per-domain recipient bcc address | `recipientBcc=user@domain.com`
2016-10-21 10:17:15 -05:00
`is_backupmx` | Mark domain as Backup MX. Must be used with parameter `primarymx` . Conflicts with parameter `transport` . | `is_backupmx=yes` (or `no` )
`primarymx` | Hostname or IP address of primary MX, smtp port number is optional. Must be used with parameter `is_backupmx` . Conflicts with parameter `transport` . | `primarymx=202.96.134.133` , `primarymx=[mail.iredmail.org]:25`
2016-11-29 23:05:25 -06:00
`catchall` | Per-domain catch-all account (a list of email addresses used to receive emails sent to non-existing addresses under same domain). Multiple addresses must be separated by comma. Set an empty value to disable catch-all support. | `catchall=user@domain.com,user2@domain.com` or `catchall=` (disable catch-all)
2016-11-30 00:04:01 -06:00
`outboundRelay` | Per-domain outbound relay. Set an empty value to disable outbound relay. | `outboundRelay=smtp:[192.168.1.2]:25` or `outboundRelay=` (disable outbound relay)
2016-06-01 10:38:58 -05:00
2016-05-14 11:18:14 -05:00
< / div >
2016-04-20 05:23:37 -05:00
2016-08-02 02:56:26 -05:00
!!! api "`GET`{: .get } `/api/domain/services/<domain>` {: .url } `Get/List all enabled per-domain services` {: .comment } `upcoming` {: .upcoming }"
!!! api "`PUT`{: .put } `/api/domain/services/<domain>` {: .url } `Manage enabled per-domain services` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params }"
2016-07-30 03:52:42 -05:00
< div class = "params params_domain_services" >
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-08-02 02:56:26 -05:00
`enableService` | Enable new services. Multiple services must be separated by comma. | `enableService=sogo,vpn,xmpp`
`disableService` | Disable existing services. Multiple services must be separated by comma. | `disableService=sogo,vpn,xmpp`
`removeAllServices` | Disable all services (including mail service) | `removeAllServices=` (empty value)
< / div >
!!! api "`PUT`{: .put } `/api/domain/admins/<domain>` {: .url } `Manage normal domain admins.` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params }"
< div class = "params params_domain_admins" >
2016-08-03 23:31:48 -05:00
!!! attention
Normal domain admin can only promote mail users under managed domains
to be a domain admin.
2016-08-02 02:56:26 -05:00
Parameter Name | Summary | Sample Usage
--- |--- |---
`addAdmin` | Add new domain admins. Multiple services must be separated by comma. | `addAdmin=one@domain.com,two@domain.com`
`removeAdmin` | Remove existing domain admins. Multiple services must be separated by comma. | `removeAdmin=one@domain.com,two@domain.com`
`removeAllAdmins` | Remove all existing domain admins. | `removeAllAdmins=` (empty value)
2016-07-30 03:52:42 -05:00
< / div >
2016-10-09 00:35:28 -05:00
### Mail User {: .toggle }
2016-04-18 09:34:43 -05:00
2016-10-09 00:35:28 -05:00
!!! api "`GET`{: .get } `/api/user/<mail>` {: .url } `Get profile of an existing mail user` {: .comment } `upcoming` {: .upcoming }"
2016-05-23 19:40:23 -05:00
!!! api "`POST`{: .post } `/api/user/<mail>` {: .url } `Create a new mail user` {: .comment } `Parameters` {: .has_params }"
< div class = "params params_user" >
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-06-01 10:38:58 -05:00
`name` | Display name | `name=My New Name`
2016-05-23 19:40:23 -05:00
`password` | Password| `password=AsTr0ng@`
2016-10-09 01:06:35 -05:00
`language` | Preferred language of iRedAdmin web UI | `language=en_US`
2016-05-23 19:40:23 -05:00
`quota` | Mailbox quota (in MB) | `quota=1024`
< / div >
2016-05-14 11:18:14 -05:00
!!! api "`DELETE`{: .delete } `/api/user/<mail>` {: .url } `Delete an existing mail user` {: .comment }"
!!! api "`PUT`{: .put } `/api/user/<mail>` {: .url } `Update profile of an existing mail user` {: .comment } `Parameters` {: .has_params} "
< div class = "params params_user" >
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-06-01 10:38:58 -05:00
`name` | Display name | `name=My New Name`
2016-05-25 10:21:27 -05:00
`password` | Password | `password=u0tBF82cIV@vi8Gme`
`quota` | Mailbox quota (in MB) | `quota=1024`
2016-10-09 01:06:35 -05:00
`accountStatus` | Enable or disable user. Possible values: `active` , `disabled` . | `accountStatus=active`
`language` | Preferred language of iRedAdmin web UI | `language=en_US`
2016-11-29 23:05:25 -06:00
`employeeid` | User ID (or Employee Number) | `employeeid=My Employee ID`
2016-05-14 11:18:14 -05:00
`transport` | Transport program | `transport=dovecot`
2016-10-09 01:06:35 -05:00
`forwarding` | Per-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses. | `forwarding=user1@domain.com,user2@domain.com,user3@domain.com`
2016-11-03 23:31:38 -06:00
`aliases` | Per-user alias addresses. Multiple addresses must be separated by comma. If empty, all per-user alias addresses owned by this user will be removed. Conflicts with parameter `addAlias` and `removeAlias` . | `aliases=user1@domain.com,user2@domain.com,user3@domain.com`
`addAlias` | Add new per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases` . | `aliases=user1@domain.com,user2@domain.com,user3@domain.com`
`removeAlias` | Remove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases` . | `aliases=user1@domain.com,user2@domain.com,user3@domain.com`
2016-05-14 11:18:14 -05:00
< / div >
2016-11-09 20:23:34 -06:00
!!! api "`POST`{: .put } `/api/user/<mail>/change_email/<new_mail>` {: .url } `Change user's email address (from '<mail>' to '<new_mail>')` {: .comment }"
2016-05-14 11:18:14 -05:00
!!! api "`PUT`{: .put } `/api/users/<domain>` {: .url } `Update profiles of all users under domain` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params }"
< div class = "params" >
Parameter Name | Comment
--- |---
2016-05-25 10:21:27 -05:00
`accountStatus` | Account status. Possible value is: active, disabled.
2016-05-14 11:18:14 -05:00
`password` | Password
2016-10-09 01:06:35 -05:00
`language` | Preferred language of iRedAdmin web UI
2016-05-25 10:21:27 -05:00
`transport` | Per-user transport
2016-05-14 11:18:14 -05:00
< / div >
2016-10-09 00:35:28 -05:00
!!! api "`POST`{: .post } `/api/verify_password/user/<mail>` {: .url } `Verify given (plain) password against the one stored in SQL/LDAP` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params} "
< div class = "params params_user" >
Parameter Name | Summary | Sample Usage
--- |--- |---
`password` | Plain password | `password=u0tBF82cIV@vi8Gme`
< / div >
2016-05-14 11:18:14 -05:00
### Mailing List {: .toggle }
!!! attention
Mailing list is only available in OpenLDAP backend. For SQL backends,
please use mail alias account as mailing list.
2016-10-13 12:46:10 -05:00
!!! api "`GET`{: .get } `/api/maillist/<mail>` {: .url } `Get profile of an existing mailing list account` {: .comment } `upcoming` {: .upcoming }"
!!! api "`POST`{: .post } `/api/maillist/<mail>` {: .url } `Create a new mailing list` {: .comment } `upcoming` {: .upcoming } `Parameters` {: .has_params }"
< div class = "params" >
Parameter Name | Summary | Sample Usage
--- |--- |---
`name` | Display name | `name=My List Name`
`accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public`
`members` | Members of mailing list. Multiple members must be separated by comma. | `members=user1@domain.com,user2@domain.com`
< / div >
2016-05-14 11:18:14 -05:00
!!! api "`DELETE`{: .delete } `/api/maillist/<mail>` {: .url } `Delete an existing mailing list` {: .comment }"
!!! api "`PUT`{: .put } `/api/maillist/<mail>` {: .url } `Update profile of an existing mailing list` {: .comment } `Parameters` {: .has_params }"
2016-05-19 06:41:31 -05:00
< div class = "params" >
2016-05-14 11:18:14 -05:00
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-06-01 10:38:58 -05:00
`name` | display name | `name=My List Name`
2016-05-14 11:18:14 -05:00
`accessPolicy` | Defines who can send email to this mailing list | `accessPolicy=public`
2016-10-31 10:18:40 -06:00
`members` | Members of mailing list. Multiple members must be separated by comma. Conflict with parameter `addMember` and `removeMember` . | `members=user1@domain.com,user2@domain.com`
`addMember` | Add new members of mailing list. Multiple members must be separated by comma. Conflict with parameter `members` . | `addMember=user1@domain.com,user2@domain.com`
`removeMember` | Remove existing members of mailing list. Multiple members must be separated by comma. Conflict with parameter `members` . | `removeMember=user1@domain.com,user2@domain.com`
2016-05-14 11:18:14 -05:00
< / div >
### Mail Alias {: .toggle }
2016-10-09 00:35:28 -05:00
!!! api "`GET`{: .get } `/api/alias/<mail>` {: .url } `Get profile of an existing mail alias` {: .comment } `upcoming` {: .upcoming }"
2016-05-25 10:21:27 -05:00
!!! api "`POST`{: .post } `/api/alias/<mail>` {: .url } `Create a new mail alias` {: .comment } `upcoming` {: .upcoming} `Parameters` {: .has_params}"
< div class = "params" >
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-10-10 02:54:52 -05:00
`name` | Display name | `name=My List Name`
2016-05-25 10:21:27 -05:00
`accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public`
2016-10-10 02:54:52 -05:00
`members` | Members of mail alias. Multiple members must be separated by comma. | `members=user1@domain.com,user2@domain.com`
2016-05-25 10:21:27 -05:00
2016-06-24 22:39:58 -05:00
!!! attention
`accessPolicy` for mail alias account is only available for SQL backends.
2016-05-25 10:21:27 -05:00
< / div >
2016-05-14 11:18:14 -05:00
!!! api "`DELETE`{: .delete } `/api/alias/<mail>` {: .url } `Delete an existing mail alias` {: .comment }"
!!! api "`PUT`{: .put } `/api/alias/<mail>` {: .url } `Update profile of an existing mail alias` {: .comment } `Parameters` {: .has_params }"
2016-05-19 06:41:31 -05:00
< div class = "params" >
2016-05-14 11:18:14 -05:00
2016-06-24 22:39:58 -05:00
!!! attention
`accessPolicy` for mail alias account is only available for SQL backends.
2016-05-14 11:18:14 -05:00
Parameter Name | Summary | Sample Usage
--- |--- |---
2016-10-10 11:12:16 -05:00
`name` | Display name | `name=My List Name`
2016-05-14 11:18:14 -05:00
`accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public`
2016-11-03 23:31:38 -06:00
`members` | Members of mail alias. Multiple members must be separated by comma. Conflict with parameter `addMember` and `removeMember` . | `members=user1@domain.com,user2@domain.com`
`addMember` | Add new members of mail alias. Multiple members must be separated by comma. Conflict with parameter `members` . | `addMember=user1@domain.com,user2@domain.com`
`removeMember` | Remove existing members of mail alias. Multiple members must be separated by comma. Conflict with parameter `members` . | `removeMember=user1@domain.com,user2@domain.com`
2016-05-14 11:18:14 -05:00
< / div >
2016-11-09 20:23:34 -06:00
!!! api "`POST`{: .put } `/api/alias/<mail>/change_email/<new_mail>` {: .url } `Change email address of alias account (from '<mail>' to '<new_mail>')` {: .comment }"
2016-05-14 11:18:14 -05:00
### Throttling {: .toggle }
!!! api "`GET`{: .get } `/api/throttle/global/inbound` {: .url } `Get global inbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/global/inbound` {: .url } `Set global inbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
!!! api "`GET`{: .get } `/api/throttle/global/outbound` {: .url } `Get global outbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/global/outbound` {: .url } `Set global inbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
!!! api "`GET`{: .get } `/api/throttle/<domain>/inbound` {: .url } `Get domain inbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/<domain>/inbound` {: .url } `Set domain inbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
!!! api "`GET`{: .get } `/api/throttle/<domain>/outbound` {: .url } `Get domain outbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/<domain>/outbound` {: .url } `Set domain outbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
!!! api "`GET`{: .get } `/api/throttle/<mail>/inbound` {: .url } `Get user inbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/<mail>/inbound` {: .url } `Set user inbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
!!! api "`GET`{: .get } `/api/throttle/<mail>/outbound` {: .url } `Get user outbound throttle settings` {: .comment }"
!!! api "`POST`{: .post } `/api/throttle/<mail>/outbound` {: .url } `Set user outbound throttle settings` {: .comment } `Parameters` {: .has_params_throttle }"
< div class = "params params_throttle" >
Parameters available for global, per-domain, per-user throttle settings.
Parameter Name | Summary | Sample Usage
--- |--- |---
`period` * | Period of time, in seconds | `period=3600` (one hour)
`msg_size` | Max size of single email, in bytes | `msg_size=10485760` (10 MB)
`max_msgs` | Number of max inbound emails | `max_msgs=20` (up to 20 messages)
`max_quota` | Cumulative size of inbound or outbound emails, in bytes | `max_quota=1048576000` (1 GB)
< / div >
2016-05-23 19:40:23 -05:00
### Export Accounts {: .toggle }
#### LDIF (LDAP backend only) {: .toggle }
2016-05-14 11:18:14 -05:00
2016-05-23 19:40:23 -05:00
!!! api "`GET`{: .get } `/api/ldif/domain/<domain>` {: .url } `Export domain to LDIF` {: .comment } `upcoming` {: .upcoming }"
!!! api "`GET`{: .get } `/api/ldif/catchall/<domain>` {: .url } `Export per-domain catch-all account to LDIF` {: .comment } `upcoming` {: .upcoming }"
!!! api "`GET`{: .get } `/api/ldif/admin/<mail>` {: .url } `Export (separated) domain admin to LDIF` {: .comment } `upcoming` {: .upcoming }"
!!! api "`GET`{: .get } `/api/ldif/user/<mail>` {: .url } `Export mail user to LDIF` {: .comment } `upcoming` {: .upcoming }"
!!! api "`GET`{: .get } `/api/ldif/maillist/<mail>` {: .url } `Export mailing list account to LDIF` {: .comment } `upcoming` {: .upcoming }"
!!! api "`GET`{: .get } `/api/ldif/alias/<mail>` {: .url } `Export mail alias account to LDIF` {: .comment } `upcoming` {: .upcoming }"
2016-05-14 11:18:14 -05:00
< script src = "./js/jquery-1.12.3.min.js" > < / script >
< script type = "text/javascript" >
$(document).ready(function(){
/* Collapse all parameters by default */
$('.params').hide();
/* Expand/Collapse ALL parameters */
$('.toggle_all').bind('click', function(){$('.params').toggle();});
/* Expand/Collapse parameters under same title/category */
$('.toggle').on('click', function() {
$(this).nextUntil('.toggle').children('.params').toggle();
});
/* Expand/Collapse parameter for current API */
$('.has_params').on('click', function() {
$(this).parent().nextUntil('.has_params').toggle();
});
/* Expand/Collapse specific parameters */
$('.has_params_throttle').bind('click', function(){$('.params_throttle').toggle();});
});
< / script >