elmau
/
iredmail-doc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

New css style for API document.

This commit is contained in:
Zhang Huangbin 2016-05-15 00:18:14 +08:00
parent b3acef396d
commit 89d6c17d76
6 changed files with 481 additions and 1040 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
en_US/faq/0-iredadmin-pro.restful.api-new.md
View File

@ -1,193 +0,0 @@
# 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
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 mail alias account | `accessPolicy=public`
> Note: `accessPolicy` for mail alias account is only available for SQL backends.
### Throttling
URL | HTTP Method | Summary
--- |---| ---
/api/throttle/global/inbound | GET | Get global inbound throttle settings
/api/throttle/global/outbound | GET | Get global outbound throttle settings
/api/throttle/global/inbound | POST | Set global inbound throttle setting
/api/throttle/global/outbound | POST | Set global outbound throttle setting
/api/throttle/<domain\>/inbound | GET | Get domain inbound throttle settings
/api/throttle/<domain\>/outbound | GET | Get domain outbound throttle settings
/api/throttle/<domain\>/inbound | POST | Set domain inbound throttle setting
/api/throttle/<domain\>/outbound | POST | Set domain outbound throttle setting
/api/throttle/<mail\>/inbound | GET | Get user inbound throttle settings
/api/throttle/<mail\>/outbound | GET | Get user outbound throttle settings
/api/throttle/<mail\>/inbound | POST | Set user inbound throttle setting
/api/throttle/<mail\>/outbound | POST | Set user outbound throttle setting
Possible `POST` parameters used to set throttle setting:
Parameter Name | Summary | Sample Usage
--- |--- |---
`period` | Period of time (in seconds) | `period=3600` (one hour)
`msg_size` | Max size of single email | `msg_size=10485760` (10 MB)
`max_msgs` | Number of max inbound emails | `max_msgs=20` (up to 20 messages)
`max_quota` | Cumulative size of all inbound emails | `max_quota=1048576000` (1 GB)
## 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)

316
en_US/faq/2-iredadmin-pro.restful.api.md
View File

@ -11,8 +11,8 @@
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>'}`.
* If operation succeed, iRedAdmin-Pro returns JSON data: `{'success': true}`.
* If operation failed, iRedAdmin-Pro returns JSON data: `{'success': false, 'msg': '<error_reason>'}`.
## Requirements
@ -41,115 +41,211 @@ 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
URL | HTTP Method | Summary
--- | --- | ---
/api/domain/<domain\> | POST | Create a new domin
/api/domain/<domain\> | DELETE | Delete an existing domain
/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`
`preferredLanguage` | default preferred language for new user | `preferredLanguage=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
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
Possible `PUT` parameters used to update account profile:
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | display name | `cn=My New Name`
`preferredLanguage` | default preferred language for new user | `preferredLanguage=en_US`
`mailQuota` | mailbox quota for this user (in MB) | `mailQuota=1024`
`password` | Password | `password=Ww0nXVEV8iv4ap@p4b`
`transport` | Transport program | `transport=dovecot`
### 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
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 mail alias account | `accessPolicy=public`
> Note: `accessPolicy` for mail alias account is only available for SQL backends.
### Throttling
URL | HTTP Method | Summary
--- |---| ---
/api/throttle/global/inbound | GET | Get global inbound throttle settings
/api/throttle/global/outbound | GET | Get global outbound throttle settings
/api/throttle/global/inbound | POST | Set global inbound throttle setting
/api/throttle/global/outbound | POST | Set global outbound throttle setting
/api/throttle/<domain\>/inbound | GET | Get domain inbound throttle settings
/api/throttle/<domain\>/outbound | GET | Get domain outbound throttle settings
/api/throttle/<domain\>/inbound | POST | Set domain inbound throttle setting
/api/throttle/<domain\>/outbound | POST | Set domain outbound throttle setting
/api/throttle/<mail\>/inbound | GET | Get user inbound throttle settings
/api/throttle/<mail\>/outbound | GET | Get user outbound throttle settings
/api/throttle/<mail\>/inbound | POST | Set user inbound throttle setting
/api/throttle/<mail\>/outbound | POST | Set user outbound throttle setting
Possible `POST` parameters used to set throttle setting:
Parameter Name | Summary | Sample Usage
--- |--- |---
`period` | Period of time (in seconds) | `period=3600` (one hour)
`msg_size` | Max size of single email | `msg_size=10485760` (10 MB)
`max_msgs` | Number of max inbound emails | `max_msgs=20` (up to 20 messages)
`max_quota` | Cumulative size of all inbound emails | `max_quota=1048576000` (1 GB)
## 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)
## APIs
Notes:
* Parameter name with a `*` mark means the parameter is required, otherwise is optional.
* replace `<domain>` in URL by the real domain name.
* replace `<mail>` in URL by the real email address.
<button type="button" class="toggle_all">Expand/Collapse All API Parameters</button>
### Domain {: .toggle }
<!--
!!! api "`GET`{: .get } `/api/domain/<domain>`{: .url } `Get profile of an existing domain`{: .comment }"
-->
!!! api "`POST`{: .post } `/api/domain/<domain>`{: .url } `Create a new domain`{: .comment } `Parameters`{: .has_params }"
<div class="params params_domain">
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | Short description of this domain name. e.g. company name | `cn=Google Inc`
`quota` | Mailbox quota for whole domain, in MB. | `quota=2048`
`language` | Default preferred language for newly created mail user | `preferredLanguage=en_US`
`defaultQuota` | Default per-user mailbox quota for newly created user | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a mail user | `maxUserQuota=2048`
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`
`numberOfLists` | Max number of mailing list accounts (LDAP only)| `numberOfLists=40`
</div>
!!! api "`DELETE`{: .delete } `/api/domain/<domain>`{: .url } `Delete an existing domain`{: .comment }"
<!--
!!! api "`PUT`{: .put } `/api/domain/<domain>`{: .url } `Update profile of an existing domain`{: .comment } `Parameters`{: .has_params }"
<div class="params params_domain">
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | Short description of this domain name. e.g. company name | `cn=Google Inc`
`quota` | Mailbox quota for whole domain, in MB. | `quota=2048`
`language` | Default preferred language for newly created mail user | `preferredLanguage=en_US`
`defaultQuota` | Default per-user mailbox quota for newly created user | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a mail user | `maxUserQuota=2048`
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`
`numberOfLists` | Max number of mailing list accounts (LDAP only)| `numberOfLists=40`
</div>
-->
### User {: .toggle }
!!! api "`POST`{: .post } `/api/user/<mail>`{: .url } `Create a new mail user`{: .comment }"
!!! 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
--- |--- |---
`cn` | Display name | `cn=My New Name`
`language` | Preferred language of web UI | `preferredLanguage=en_US`
`mailQuota` | User's mailbox quota, in MB | `mailQuota=1024`
`transport` | Transport program | `transport=dovecot`
</div>
!!! api "`PUT`{: .put } `/api/user/<mail>/password`{: .url } `Update user's password`{: .comment } `upcoming`{: .upcoming } `Parameters`{: .has_params }"
<div class="params">
Parameter Name | Comment
--- |---
`password` | Password
</div>
!!! 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
--- |---
accountStatus | Account status. Possible value is: active, disabled.
language | Preferred language of web UI
transport | Per-user transport
</div>
!!! api "`PUT`{: .put } `/api/users/<domain>/password`{: .url } `Update passwords of all users under domain`{: .comment } `upcoming`{: .upcoming } `Parameters`{: .has_params }"
<div class="params">
Parameter Name | Comment
--- |---
`password` | Password
</div>
### Mailing List {: .toggle }
!!! attention
Mailing list is only available in OpenLDAP backend. For SQL backends,
please use mail alias account as mailing list.
!!! api "`POST`{: .post } `/api/maillist/<mail>`{: .url } `Create a new mailing list`{: .comment }"
!!! 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 }"
<div class="params params_maillist">
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | display name | `cn=My List Name`
`accessPolicy` | Defines who can send email to this mailing list | `accessPolicy=public`
</div>
### Mail Alias {: .toggle }
!!! api "`POST`{: .post } `/api/alias/<mail>`{: .url } `Create a new mail alias`{: .comment }"
!!! 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 }"
<div class="params params_alias">
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | display name | `cn=My List Name`
`accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public`
> Note: `accessPolicy` for mail alias account is only available for SQL backends.
</div>
### 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>
<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>

49
html/css/markdown.css
View File

@ -320,6 +320,9 @@ pre { margin-left: 30px; }
p, ul, ol { font-size: 17px; }
li { line-height: 26px; }
.f_left { float: left; }
.f_right { float: right; }
/*
.note {
background: #e7f2fa;
@ -370,6 +373,14 @@ li { line-height: 26px; }
.warning { background: #FFFFE1; }
.attention p { margin-top: 4px; }
/* Table */
table { border: 1px solid black; border-collapse: collapse;}
th { padding: 5px 10px 5px 10px; }
td { padding: 5px 10px 5px 10px; }
th, td { border: 1px solid black; }
button { font-size: 16px; padding: 5px 5px 5px 5px; }
/* Style for API document */
.api {
line-height: 18px;
@ -382,21 +393,32 @@ li { line-height: 26px; }
padding: 0px 12px 0px 5px;
}
/* Table */
table { border: 1px solid black; border-collapse: collapse;}
th { padding: 5px 10px 5px 10px; }
td { padding: 5px 10px 5px 10px; }
th, td { border: 1px solid black; }
.api code.url { background-color: white; color: black; display: inline-block; }
.api code.get,
.api code.post,
.api code.put,
.api code.delete,
.api code.has_params,
.api code.has_params_throttle
{
display: inline-block;
width: 60px;
text-align: center;
}
.api code.get { background-color: #0f6ab4; }
.api code.post { background-color: #10a54a; }
.api code.put { background-color: #c5862b; padding-left: 5px; padding-right: 5px;}
.api code.delete { background-color: #a41e22; }
.api code.get, .api code.post, .api code.put, .api code.delete {
display: inline-block;
width: 60px;
text-align: center;
.api code.upcoming { background-color: #0f6ab4; text-transform: uppercase; font-size: 12px; }
.api code.new { background-color: #10a54a; text-transform: uppercase; }
.api code.has_params,
.api code.has_params_throttle {
background-color: #0064cd;
font-size: 12px;
float: right;
width: auto;
cursor: pointer;
-webkit-appearance: button;
}
.api code.comment {
color: black;
@ -418,10 +440,7 @@ th, td { border: 1px solid black; }
vertical-align: middle;
margin-bottom: 20px;
}
.api table thead { background-color: #ccc; }
.api th { padding: 0px 10px 0px 10px; }
.api td { padding: 0px 10px 0px 10px; }
.admonition table thead {
background-color: #f4f8e9;
}
/* END style for API Document */

516
html/iredadmin-pro.restful.api-new.html
View File

@ -1,516 +0,0 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>iRedAdmin-Pro: RESTful API</title>
<link rel="stylesheet" type="text/css" href="./css/markdown.css" />
</head>
<body>
<div id="navigation">
<a href="/index.html" target="_blank">
<img alt="iRedMail web site"
src="./images/logo-iredmail.png"
style="vertical-align: middle; height: 30px;"
/>&nbsp;
<span>iRedMail</span>
</a>
&nbsp;&nbsp;//&nbsp;&nbsp;<a href="./index.html">Document Index</a></div><h1 id="iredadmin-pro-restful-api">iRedAdmin-Pro: RESTful API</h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you need an API which has not yet been implemented, don't hesitate to
<a href="../contact.html">contact us</a>.</p>
</div>
<div class="toc">
<ul>
<li><a href="#iredadmin-pro-restful-api">iRedAdmin-Pro: RESTful API</a><ul>
<li><a href="#changelog">ChangeLog</a></li>
<li><a href="#summary">Summary</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#enable-restful-api">Enable RESTful API</a></li>
<li><a href="#apis">APIs</a><ul>
<li><a href="#domain">Domain</a></li>
<li><a href="#user">User</a></li>
<li><a href="#mailing-list">Mailing List</a></li>
<li><a href="#mail-alias">Mail Alias</a></li>
<li><a href="#throttling">Throttling</a></li>
</ul>
</li>
<li><a href="#sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</a></li>
</ul>
</li>
</ul>
</div>
<h2 id="changelog">ChangeLog</h2>
<ul>
<li>
<p>May XX, 2016:</p>
<ul>
<li>NEW APIs:<ul>
<li><code>/api/user/&lt;mail&gt;/password</code></li>
<li><code>/api/users/&lt;domain&gt;</code></li>
<li><code>/api/users/&lt;domain&gt;/password</code></li>
</ul>
</li>
<li>parameter used to update account profile <code>preferredLanguage</code> has been changed to <code>language</code>.</li>
<li>API used to update user password is now: <code>/api/user/&lt;mail&gt;/password</code> (old is <code>/api/user/&lt;mail&gt;</code>)</li>
</ul>
</li>
<li>
<p>May 3, 2016: initial publish.</p>
</li>
</ul>
<h2 id="summary">Summary</h2>
<p>iRedAdmin-Pro RESTful API will return message in JSON format.</p>
<ul>
<li>If operation succeed, client will receive JSON data: <code>{'success': true}</code>.</li>
<li>If operation failed, client will receive JSON data: <code>{'success': false, 'msg': '&lt;error_reason&gt;'}</code>.</li>
</ul>
<h2 id="requirements">Requirements</h2>
<p>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.</p>
<h2 id="enable-restful-api">Enable RESTful API</h2>
<p>RESTful API is disabled by default, to enable it, please add setting below in
iRedAdmin-Pro config file <code>settings.py</code>:</p>
<pre><code>ENABLE_RESTFUL_API = True
</code></pre>
<p>To restrict API access to few IP addresses, please also add settings below in
iRedAdmin-Pro config file:</p>
<pre><code># Enable restriction
RESTRICT_API_ACCESS = True
# List all IP addresses of allowed client for API access.
RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
</code></pre>
<p>Restarting Apache or uwsgi (if you're running Nginx) is required.</p>
<h2 id="apis">APIs</h2>
<p>Notes:</p>
<ul>
<li>replace <code>&lt;domain&gt;</code> in URL by the real domain name.</li>
<li>replace <code>&lt;mail&gt;</code> in URL by the real email address.</li>
</ul>
<h3 id="domain">Domain</h3>
<div class="admonition api">
<p class="admonition-title"><code>/api/domain/&lt;domain&gt;</code> <code>POST</code> <code>Create a new domain</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/domain/&lt;domain&gt;</code> <code>DELETE</code> <code>Delete an existing domain</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/domain/&lt;domain&gt;</code> <code>PUT</code> <code>Update profile of an existing domain</code></p>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>cn</code></td>
<td>the short description of this domain name. e.g. company name</td>
<td><code>cn=iRedMail Project</code></td>
</tr>
<tr>
<td><code>quota</code></td>
<td>a integer number for mailbox quota (for whole domain, in MB)</td>
<td><code>quota=20480</code></td>
</tr>
<tr>
<td><code>language</code></td>
<td>default preferred language for new user</td>
<td><code>language=en_US</code></td>
</tr>
<tr>
<td><code>defaultQuota</code></td>
<td>default mailbox quota for new user</td>
<td><code>defaultQuota=1024</code></td>
</tr>
<tr>
<td><code>maxUserQuota</code></td>
<td>Max mailbox quota of a single mail user</td>
<td><code>maxUserQuota=2048</code></td>
</tr>
<tr>
<td><code>numberOfUsers</code></td>
<td>Max number of mail user accounts</td>
<td><code>numberOfUsers=20</code></td>
</tr>
<tr>
<td><code>numberOfAliases</code></td>
<td>Max number of mail alias accounts</td>
<td><code>numberOfAliases=30</code></td>
</tr>
</tbody>
</table>
</div>
<h3 id="user">User</h3>
<div class="admonition api">
<p class="admonition-title"><code>/api/user/&lt;mail&gt;</code> <code>POST</code> <code>Create a new mail user</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/user/&lt;mail&gt;</code> <code>DELETE</code> <code>Delete an existing mail user</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/user/&lt;mail&gt;</code> <code>PUT</code> <code>Update profile of an existing mail user</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/users/&lt;domain&gt;</code> <code>PUT</code> <code>Update profiles of all mail user under domain</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code>/api/users/&lt;domain&gt;/password</code> <code>PUT</code> <code>Update passwords of all users under domain</code></p>
<p id="param">Required parameter:</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>password</code></td>
<td><code>password=Ww0nXVEV8iv4ap@p4b</code></td>
</tr>
</tbody>
</table>
</div>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/user/&lt;mail></td>
<td>POST</td>
<td>Create a new mail user</td>
</tr>
<tr>
<td>/api/user/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mail user</td>
</tr>
<tr>
<td>/api/user/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mail user</td>
</tr>
<tr>
<td>/api/users/&lt;domain></td>
<td>PUT</td>
<td>Update profiles for all users under domain <code>&lt;domain&gt;</code></td>
</tr>
<tr>
<td>/api/users/&lt;domain>/password</td>
<td>PUT</td>
<td>Update passwords of all users under domain <code>&lt;domain&gt;</code></td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile (<code>/api/user/&lt;mail&gt;</code>):</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>cn</code></td>
<td>display name</td>
<td><code>cn=John Smith</code></td>
</tr>
<tr>
<td><code>accountStatus</code></td>
<td>Account status</td>
<td><code>accountStatus=disabled</code> (or <code>active</code>)</td>
</tr>
<tr>
<td><code>language</code></td>
<td>default preferred language for new user</td>
<td><code>language=en_US</code></td>
</tr>
<tr>
<td><code>transport</code></td>
<td>Transport program</td>
<td><code>transport=dovecot</code></td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update profiles for all users under domain (<code>/api/users/&lt;domain&gt;</code>):</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>accountStatus</code></td>
<td>Account status</td>
<td><code>accountStatus=disabled</code> (or <code>active</code>)</td>
</tr>
<tr>
<td><code>language</code></td>
<td>default preferred language for new user</td>
<td><code>language=en_US</code></td>
</tr>
<tr>
<td><code>transport</code></td>
<td>Transport program</td>
<td><code>transport=dovecot</code></td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update passwords of all users under domain (<code>/api/users/&lt;domain&gt;/password</code>):</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>password</code></td>
<td>Update passwords of all users under domain</td>
<td><code>password=Ww0nXVEV8iv4ap@p4b</code></td>
</tr>
</tbody>
</table>
<h3 id="mailing-list">Mailing List</h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is applicable to OpenLDAP. For SQL backends, please use mail alias
account as mailing list.</p>
</div>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>POST</td>
<td>Create a new mailing list</td>
</tr>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mailing list</td>
</tr>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mailing list</td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>cn</code></td>
<td>display name</td>
<td><code>cn=My List Name</code></td>
</tr>
<tr>
<td><code>accessPolicy</code></td>
<td>Defines who can send email to this mailing list</td>
<td><code>accessPolicy=public</code></td>
</tr>
</tbody>
</table>
<h3 id="mail-alias">Mail Alias</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/alias/&lt;mail></td>
<td>POST</td>
<td>Create a new mail alias</td>
</tr>
<tr>
<td>/api/alias/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mail alias</td>
</tr>
<tr>
<td>/api/alias/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mail alias</td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>cn</code></td>
<td>display name</td>
<td><code>cn=My List Name</code></td>
</tr>
<tr>
<td><code>accessPolicy</code></td>
<td>Defines who can send email to this mail alias account</td>
<td><code>accessPolicy=public</code></td>
</tr>
</tbody>
</table>
<blockquote>
<p>Note: <code>accessPolicy</code> for mail alias account is only available for SQL backends.</p>
</blockquote>
<h3 id="throttling">Throttling</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/throttle/global/inbound</td>
<td>GET</td>
<td>Get global inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/global/outbound</td>
<td>GET</td>
<td>Get global outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/global/inbound</td>
<td>POST</td>
<td>Set global inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/global/outbound</td>
<td>POST</td>
<td>Set global outbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/inbound</td>
<td>GET</td>
<td>Get domain inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/outbound</td>
<td>GET</td>
<td>Get domain outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/inbound</td>
<td>POST</td>
<td>Set domain inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/outbound</td>
<td>POST</td>
<td>Set domain outbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/inbound</td>
<td>GET</td>
<td>Get user inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/outbound</td>
<td>GET</td>
<td>Get user outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/inbound</td>
<td>POST</td>
<td>Set user inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/outbound</td>
<td>POST</td>
<td>Set user outbound throttle setting</td>
</tr>
</tbody>
</table>
<p>Possible <code>POST</code> parameters used to set throttle setting:</p>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Summary</th>
<th>Sample Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>period</code></td>
<td>Period of time (in seconds)</td>
<td><code>period=3600</code> (one hour)</td>
</tr>
<tr>
<td><code>msg_size</code></td>
<td>Max size of single email</td>
<td><code>msg_size=10485760</code> (10 MB)</td>
</tr>
<tr>
<td><code>max_msgs</code></td>
<td>Number of max inbound emails</td>
<td><code>max_msgs=20</code> (up to 20 messages)</td>
</tr>
<tr>
<td><code>max_quota</code></td>
<td>Cumulative size of all inbound emails</td>
<td><code>max_quota=1048576000</code> (1 GB)</td>
</tr>
</tbody>
</table>
<h2 id="sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</h2>
<ul>
<li><a href="./iredadmin-pro.restful.api.curl.html">iRedAdmin-Pro RESTful API (interact with <code>curl</code>)</a></li>
<li><a href="./iredadmin-pro.restful.api.python.html">iRedAdmin-Pro RESTful API (interact with Python)</a></li>
</ul><p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. If you found something wrong, please do <a href="http://www.iredmail.org/contact.html">contact us</a> to fix it.<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-3293801-21', 'auto');
ga('send', 'pageview');
</script>
</body></html>

442
html/iredadmin-pro.restful.api.html
View File

@ -26,6 +26,7 @@
<li><a href="#summary">Summary</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#enable-restful-api">Enable RESTful API</a></li>
<li><a href="#sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</a></li>
<li><a href="#apis">APIs</a><ul>
<li><a href="#domain">Domain</a></li>
<li><a href="#user">User</a></li>
@ -34,7 +35,6 @@
<li><a href="#throttling">Throttling</a></li>
</ul>
</li>
<li><a href="#sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</a></li>
</ul>
</li>
</ul>
@ -42,8 +42,8 @@
<h2 id="summary">Summary</h2>
<p>iRedAdmin-Pro RESTful API will return message in JSON format.</p>
<ul>
<li>If operation succeed, client will receive JSON data: <code>{'success': true}</code>.</li>
<li>If operation failed, client will receive JSON data: <code>{'success': false, 'msg': '&lt;error_reason&gt;'}</code>.</li>
<li>If operation succeed, iRedAdmin-Pro returns JSON data: <code>{'success': true}</code>.</li>
<li>If operation failed, iRedAdmin-Pro returns JSON data: <code>{'success': false, 'msg': '&lt;error_reason&gt;'}</code>.</li>
</ul>
<h2 id="requirements">Requirements</h2>
<ul>
@ -66,40 +66,28 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
</code></pre>
<p>Restarting Apache or uwsgi (if you're running Nginx) is required.</p>
<h2 id="sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</h2>
<ul>
<li><a href="./iredadmin-pro.restful.api.curl.html">iRedAdmin-Pro RESTful API (interact with <code>curl</code>)</a></li>
<li><a href="./iredadmin-pro.restful.api.python.html">iRedAdmin-Pro RESTful API (interact with Python)</a></li>
</ul>
<h2 id="apis">APIs</h2>
<p>Notes:</p>
<ul>
<li>Parameter name with a <code>*</code> mark means the parameter is required, otherwise is optional.</li>
<li>replace <code>&lt;domain&gt;</code> in URL by the real domain name.</li>
<li>replace <code>&lt;mail&gt;</code> in URL by the real email address.</li>
</ul>
<h3 id="domain">Domain</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/domain/&lt;domain></td>
<td>POST</td>
<td>Create a new domin</td>
</tr>
<tr>
<td>/api/domain/&lt;domain></td>
<td>DELETE</td>
<td>Delete an existing domain</td>
</tr>
<tr>
<td>/api/domain/&lt;domain></td>
<td>PUT</td>
<td>Update profile of an existing domain</td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
<p><button type="button" class="toggle_all">Expand/Collapse All API Parameters</button></p>
<h3 class="toggle" id="domain">Domain</h3>
<!--
!!! api "`GET`{: .get } `/api/domain/<domain>`{: .url } `Get profile of an existing domain`{: .comment }"
-->
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/domain/&lt;domain&gt;</code> <code class="comment">Create a new domain</code> <code class="has_params">Parameters</code></p>
<div class="params params_domain">
<table>
<thead>
<tr>
@ -111,27 +99,27 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
<tbody>
<tr>
<td><code>cn</code></td>
<td>the short description of this domain name. e.g. company name</td>
<td><code>cn=iRedMail Project</code></td>
<td>Short description of this domain name. e.g. company name</td>
<td><code>cn=Google Inc</code></td>
</tr>
<tr>
<td><code>quota</code></td>
<td>a integer number for mailbox quota (for whole domain, in MB)</td>
<td><code>quota=20480</code></td>
<td>Mailbox quota for whole domain, in MB.</td>
<td><code>quota=2048</code></td>
</tr>
<tr>
<td><code>preferredLanguage</code></td>
<td>default preferred language for new user</td>
<td><code>language</code></td>
<td>Default preferred language for newly created mail user</td>
<td><code>preferredLanguage=en_US</code></td>
</tr>
<tr>
<td><code>defaultQuota</code></td>
<td>default mailbox quota for new user</td>
<td>Default per-user mailbox quota for newly created user</td>
<td><code>defaultQuota=1024</code></td>
</tr>
<tr>
<td><code>maxUserQuota</code></td>
<td>Max mailbox quota of a single mail user</td>
<td>Max mailbox quota of a mail user</td>
<td><code>maxUserQuota=2048</code></td>
</tr>
<tr>
@ -144,36 +132,49 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
<td>Max number of mail alias accounts</td>
<td><code>numberOfAliases=30</code></td>
</tr>
</tbody>
</table>
<h3 id="user">User</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/user/&lt;mail></td>
<td>POST</td>
<td>Create a new mail user</td>
</tr>
<tr>
<td>/api/user/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mail user</td>
</tr>
<tr>
<td>/api/user/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mail user</td>
<td><code>numberOfLists</code></td>
<td>Max number of mailing list accounts (LDAP only)</td>
<td><code>numberOfLists=40</code></td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
</div>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="delete">DELETE</code> <code class="url">/api/domain/&lt;domain&gt;</code> <code class="comment">Delete an existing domain</code></p>
</div>
<!--
!!! api "`PUT`{: .put } `/api/domain/<domain>`{: .url } `Update profile of an existing domain`{: .comment } `Parameters`{: .has_params }"
<div class="params params_domain">
Parameter Name | Summary | Sample Usage
--- |--- |---
`cn` | Short description of this domain name. e.g. company name | `cn=Google Inc`
`quota` | Mailbox quota for whole domain, in MB. | `quota=2048`
`language` | Default preferred language for newly created mail user | `preferredLanguage=en_US`
`defaultQuota` | Default per-user mailbox quota for newly created user | `defaultQuota=1024`
`maxUserQuota` | Max mailbox quota of a mail user | `maxUserQuota=2048`
`numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20`
`numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30`
`numberOfLists` | Max number of mailing list accounts (LDAP only)| `numberOfLists=40`
</div>
-->
<h3 class="toggle" id="user">User</h3>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/user/&lt;mail&gt;</code> <code class="comment">Create a new mail user</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="delete">DELETE</code> <code class="url">/api/user/&lt;mail&gt;</code> <code class="comment">Delete an existing mail user</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/user/&lt;mail&gt;</code> <code class="comment">Update profile of an existing mail user</code> <code class="has_params">Parameters</code> </p>
<div class="params params_user">
<table>
<thead>
<tr>
@ -185,64 +186,116 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
<tbody>
<tr>
<td><code>cn</code></td>
<td>display name</td>
<td>Display name</td>
<td><code>cn=My New Name</code></td>
</tr>
<tr>
<td><code>preferredLanguage</code></td>
<td>default preferred language for new user</td>
<td><code>language</code></td>
<td>Preferred language of web UI</td>
<td><code>preferredLanguage=en_US</code></td>
</tr>
<tr>
<td><code>mailQuota</code></td>
<td>mailbox quota for this user (in MB)</td>
<td>User's mailbox quota, in MB</td>
<td><code>mailQuota=1024</code></td>
</tr>
<tr>
<td><code>password</code></td>
<td>Password</td>
<td><code>password=Ww0nXVEV8iv4ap@p4b</code></td>
</tr>
<tr>
<td><code>transport</code></td>
<td>Transport program</td>
<td><code>transport=dovecot</code></td>
</tr>
</tbody>
</table>
<h3 id="mailing-list">Mailing List</h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is applicable to OpenLDAP. For SQL backends, please use mail alias
account as mailing list.</p>
</div>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/user/&lt;mail&gt;/password</code> <code class="comment">Update user's password</code> <code class="upcoming">upcoming</code> <code class="has_params">Parameters</code></p>
<div class="params">
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
<th>Parameter Name</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>POST</td>
<td>Create a new mailing list</td>
</tr>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mailing list</td>
</tr>
<tr>
<td>/api/maillist/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mailing list</td>
<td><code>password</code></td>
<td>Password</td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
</div>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/users/&lt;domain&gt;</code> <code class="comment">Update profiles of all users under domain</code> <code class="upcoming">upcoming</code> <code class="has_params">Parameters</code></p>
<div class="params">
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>accountStatus</td>
<td>Account status. Possible value is: active, disabled.</td>
</tr>
<tr>
<td>language</td>
<td>Preferred language of web UI</td>
</tr>
<tr>
<td>transport</td>
<td>Per-user transport</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/users/&lt;domain&gt;/password</code> <code class="comment">Update passwords of all users under domain</code> <code class="upcoming">upcoming</code> <code class="has_params">Parameters</code></p>
<div class="params">
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>password</code></td>
<td>Password</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 class="toggle" id="mailing-list">Mailing List</h3>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>Mailing list is only available in OpenLDAP backend. For SQL backends,
please use mail alias account as mailing list.</p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/maillist/&lt;mail&gt;</code> <code class="comment">Create a new mailing list</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="delete">DELETE</code> <code class="url">/api/maillist/&lt;mail&gt;</code> <code class="comment">Delete an existing mailing list</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/maillist/&lt;mail&gt;</code> <code class="comment">Update profile of an existing mailing list</code> <code class="has_params">Parameters</code></p>
<div class="params params_maillist">
<table>
<thead>
<tr>
@ -264,34 +317,20 @@ account as mailing list.</p>
</tr>
</tbody>
</table>
<h3 id="mail-alias">Mail Alias</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/alias/&lt;mail></td>
<td>POST</td>
<td>Create a new mail alias</td>
</tr>
<tr>
<td>/api/alias/&lt;mail></td>
<td>DELETE</td>
<td>Delete an existing mail alias</td>
</tr>
<tr>
<td>/api/alias/&lt;mail></td>
<td>PUT</td>
<td>Update profile of an existing mail alias</td>
</tr>
</tbody>
</table>
<p>Possible <code>PUT</code> parameters used to update account profile:</p>
</div>
</div>
<h3 class="toggle" id="mail-alias">Mail Alias</h3>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/alias/&lt;mail&gt;</code> <code class="comment">Create a new mail alias</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="delete">DELETE</code> <code class="url">/api/alias/&lt;mail&gt;</code> <code class="comment">Delete an existing mail alias</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="put">PUT</code> <code class="url">/api/alias/&lt;mail&gt;</code> <code class="comment">Update profile of an existing mail alias</code> <code class="has_params">Parameters</code></p>
<div class="params params_alias">
<table>
<thead>
<tr>
@ -316,79 +355,48 @@ account as mailing list.</p>
<blockquote>
<p>Note: <code>accessPolicy</code> for mail alias account is only available for SQL backends.</p>
</blockquote>
<h3 id="throttling">Throttling</h3>
<table>
<thead>
<tr>
<th>URL</th>
<th>HTTP Method</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/throttle/global/inbound</td>
<td>GET</td>
<td>Get global inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/global/outbound</td>
<td>GET</td>
<td>Get global outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/global/inbound</td>
<td>POST</td>
<td>Set global inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/global/outbound</td>
<td>POST</td>
<td>Set global outbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/inbound</td>
<td>GET</td>
<td>Get domain inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/outbound</td>
<td>GET</td>
<td>Get domain outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/inbound</td>
<td>POST</td>
<td>Set domain inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;domain>/outbound</td>
<td>POST</td>
<td>Set domain outbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/inbound</td>
<td>GET</td>
<td>Get user inbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/outbound</td>
<td>GET</td>
<td>Get user outbound throttle settings</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/inbound</td>
<td>POST</td>
<td>Set user inbound throttle setting</td>
</tr>
<tr>
<td>/api/throttle/&lt;mail>/outbound</td>
<td>POST</td>
<td>Set user outbound throttle setting</td>
</tr>
</tbody>
</table>
<p>Possible <code>POST</code> parameters used to set throttle setting:</p>
</div>
</div>
<h3 class="toggle" id="throttling">Throttling</h3>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/global/inbound</code> <code class="comment">Get global inbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/global/inbound</code> <code class="comment">Set global inbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/global/outbound</code> <code class="comment">Get global outbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/global/outbound</code> <code class="comment">Set global inbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/&lt;domain&gt;/inbound</code> <code class="comment">Get domain inbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/&lt;domain&gt;/inbound</code> <code class="comment">Set domain inbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/&lt;domain&gt;/outbound</code> <code class="comment">Get domain outbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/&lt;domain&gt;/outbound</code> <code class="comment">Set domain outbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/&lt;mail&gt;/inbound</code> <code class="comment">Get user inbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/&lt;mail&gt;/inbound</code> <code class="comment">Set user inbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="get">GET</code> <code class="url">/api/throttle/&lt;mail&gt;/outbound</code> <code class="comment">Get user outbound throttle settings</code></p>
</div>
<div class="admonition api">
<p class="admonition-title"><code class="post">POST</code> <code class="url">/api/throttle/&lt;mail&gt;/outbound</code> <code class="comment">Set user outbound throttle settings</code> <code class="has_params_throttle">Parameters</code></p>
<div class="params params_throttle">
<p>Parameters available for global, per-domain, per-user throttle settings.</p>
<table>
<thead>
<tr>
@ -399,13 +407,13 @@ account as mailing list.</p>
</thead>
<tbody>
<tr>
<td><code>period</code></td>
<td>Period of time (in seconds)</td>
<td><code>period</code> *</td>
<td>Period of time, in seconds</td>
<td><code>period=3600</code> (one hour)</td>
</tr>
<tr>
<td><code>msg_size</code></td>
<td>Max size of single email</td>
<td>Max size of single email, in bytes</td>
<td><code>msg_size=10485760</code> (10 MB)</td>
</tr>
<tr>
@ -415,16 +423,38 @@ account as mailing list.</p>
</tr>
<tr>
<td><code>max_quota</code></td>
<td>Cumulative size of all inbound emails</td>
<td>Cumulative size of inbound or outbound emails, in bytes</td>
<td><code>max_quota=1048576000</code> (1 GB)</td>
</tr>
</tbody>
</table>
<h2 id="sample-code-to-interact-with-iredadmin-pro-restful-api">Sample code to interact with iRedAdmin-Pro RESTful API</h2>
<ul>
<li><a href="./iredadmin-pro.restful.api.curl.html">iRedAdmin-Pro RESTful API (interact with <code>curl</code>)</a></li>
<li><a href="./iredadmin-pro.restful.api.python.html">iRedAdmin-Pro RESTful API (interact with Python)</a></li>
</ul><p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. If you found something wrong, please do <a href="http://www.iredmail.org/contact.html">contact us</a> to fix it.<script>
</div>
</div>
<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><p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. If you found something wrong, please do <a href="http://www.iredmail.org/contact.html">contact us</a> to fix it.<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

5
html/js/jquery-1.12.3.min.js vendored Normal file
View File

File diff suppressed because one or more lines are too long