From 89d6c17d763ce8e7d271ee83a47cf04c4b305f95 Mon Sep 17 00:00:00 2001 From: Zhang Huangbin Date: Sun, 15 May 2016 00:18:14 +0800 Subject: [PATCH] New css style for API document. --- en_US/faq/0-iredadmin-pro.restful.api-new.md | 193 ------- en_US/faq/2-iredadmin-pro.restful.api.md | 316 ++++++++---- html/css/markdown.css | 49 +- html/iredadmin-pro.restful.api-new.html | 516 ------------------- html/iredadmin-pro.restful.api.html | 442 ++++++++-------- html/js/jquery-1.12.3.min.js | 5 + 6 files changed, 481 insertions(+), 1040 deletions(-) delete mode 100644 en_US/faq/0-iredadmin-pro.restful.api-new.md delete mode 100644 html/iredadmin-pro.restful.api-new.html create mode 100644 html/js/jquery-1.12.3.min.js diff --git a/en_US/faq/0-iredadmin-pro.restful.api-new.md b/en_US/faq/0-iredadmin-pro.restful.api-new.md deleted file mode 100644 index d832f5e8..00000000 --- a/en_US/faq/0-iredadmin-pro.restful.api-new.md +++ /dev/null @@ -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//password` - * `/api/users/` - * `/api/users//password` - * parameter used to update account profile `preferredLanguage` has been changed to `language`. - * API used to update user password is now: `/api/user//password` (old is `/api/user/`) - -* 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': ''}`. - -## 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 `` in URL by the real domain name. -* replace `` in URL by the real email address. - -### Domain - -!!! api "`/api/domain/` `POST` `Create a new domain`" -!!! api "`/api/domain/` `DELETE` `Delete an existing domain`" -!!! api "`/api/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/` `POST` `Create a new mail user`" -!!! api "`/api/user/` `DELETE` `Delete an existing mail user`" -!!! api "`/api/user/` `PUT` `Update profile of an existing mail user`" -!!! api "`/api/users/` `PUT` `Update profiles of all mail user under domain`" -!!! api "`/api/users//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/ | POST | Create a new mail user -/api/user/ | DELETE | Delete an existing mail user -/api/user/ | PUT | Update profile of an existing mail user -/api/users/ | PUT | Update profiles for all users under domain `` -/api/users//password | PUT | Update passwords of all users under domain `` - -Possible `PUT` parameters used to update account profile (`/api/user/`): - -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/`): - -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//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/ | POST | Create a new mailing list -/api/maillist/ | DELETE | Delete an existing mailing list -/api/maillist/ | 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/ | POST | Create a new mail alias -/api/alias/ | DELETE | Delete an existing mail alias -/api/alias/ | 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//inbound | GET | Get domain inbound throttle settings -/api/throttle//outbound | GET | Get domain outbound throttle settings -/api/throttle//inbound | POST | Set domain inbound throttle setting -/api/throttle//outbound | POST | Set domain outbound throttle setting -/api/throttle//inbound | GET | Get user inbound throttle settings -/api/throttle//outbound | GET | Get user outbound throttle settings -/api/throttle//inbound | POST | Set user inbound throttle setting -/api/throttle//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) diff --git a/en_US/faq/2-iredadmin-pro.restful.api.md b/en_US/faq/2-iredadmin-pro.restful.api.md index 7a77f9be..28e30966 100644 --- a/en_US/faq/2-iredadmin-pro.restful.api.md +++ b/en_US/faq/2-iredadmin-pro.restful.api.md @@ -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': ''}`. +* If operation succeed, iRedAdmin-Pro returns JSON data: `{'success': true}`. +* If operation failed, iRedAdmin-Pro returns JSON data: `{'success': false, 'msg': ''}`. ## 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 `` in URL by the real domain name. -* replace `` in URL by the real email address. - -### Domain - -URL | HTTP Method | Summary ---- | --- | --- -/api/domain/ | POST | Create a new domin -/api/domain/ | DELETE | Delete an existing domain -/api/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/ | POST | Create a new mail user -/api/user/ | DELETE | Delete an existing mail user -/api/user/ | 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/ | POST | Create a new mailing list -/api/maillist/ | DELETE | Delete an existing mailing list -/api/maillist/ | 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/ | POST | Create a new mail alias -/api/alias/ | DELETE | Delete an existing mail alias -/api/alias/ | 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//inbound | GET | Get domain inbound throttle settings -/api/throttle//outbound | GET | Get domain outbound throttle settings -/api/throttle//inbound | POST | Set domain inbound throttle setting -/api/throttle//outbound | POST | Set domain outbound throttle setting -/api/throttle//inbound | GET | Get user inbound throttle settings -/api/throttle//outbound | GET | Get user outbound throttle settings -/api/throttle//inbound | POST | Set user inbound throttle setting -/api/throttle//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 `` in URL by the real domain name. +* replace `` in URL by the real email address. + + + +### Domain {: .toggle } + + +!!! api "`POST`{: .post } `/api/domain/`{: .url } `Create a new domain`{: .comment } `Parameters`{: .has_params }" + +
+ + 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` + +
+ +!!! api "`DELETE`{: .delete } `/api/domain/`{: .url } `Delete an existing domain`{: .comment }" + + + +### User {: .toggle } + +!!! api "`POST`{: .post } `/api/user/`{: .url } `Create a new mail user`{: .comment }" +!!! api "`DELETE`{: .delete } `/api/user/`{: .url } `Delete an existing mail user`{: .comment }" +!!! api "`PUT`{: .put } `/api/user/`{: .url } `Update profile of an existing mail user`{: .comment } `Parameters`{: .has_params} " + +
+ + 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` + +
+ +!!! api "`PUT`{: .put } `/api/user//password`{: .url } `Update user's password`{: .comment } `upcoming`{: .upcoming } `Parameters`{: .has_params }" + +
+ + Parameter Name | Comment + --- |--- + `password` | Password + +
+ +!!! api "`PUT`{: .put } `/api/users/`{: .url } `Update profiles of all users under domain`{: .comment } `upcoming`{: .upcoming } `Parameters`{: .has_params }" + +
+ + Parameter Name | Comment + --- |--- + accountStatus | Account status. Possible value is: active, disabled. + language | Preferred language of web UI + transport | Per-user transport + +
+ +!!! api "`PUT`{: .put } `/api/users//password`{: .url } `Update passwords of all users under domain`{: .comment } `upcoming`{: .upcoming } `Parameters`{: .has_params }" + +
+ + Parameter Name | Comment + --- |--- + `password` | Password + +
+ +### 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/`{: .url } `Create a new mailing list`{: .comment }" +!!! api "`DELETE`{: .delete } `/api/maillist/`{: .url } `Delete an existing mailing list`{: .comment }" +!!! api "`PUT`{: .put } `/api/maillist/`{: .url } `Update profile of an existing mailing list`{: .comment } `Parameters`{: .has_params }" + +
+ + 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 {: .toggle } + +!!! api "`POST`{: .post } `/api/alias/`{: .url } `Create a new mail alias`{: .comment }" +!!! api "`DELETE`{: .delete } `/api/alias/`{: .url } `Delete an existing mail alias`{: .comment }" +!!! api "`PUT`{: .put } `/api/alias/`{: .url } `Update profile of an existing mail alias`{: .comment } `Parameters`{: .has_params }" + +
+ + 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 {: .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//inbound`{: .url } `Get domain inbound throttle settings`{: .comment }" +!!! api "`POST`{: .post } `/api/throttle//inbound`{: .url } `Set domain inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" +!!! api "`GET`{: .get } `/api/throttle//outbound`{: .url } `Get domain outbound throttle settings`{: .comment }" +!!! api "`POST`{: .post } `/api/throttle//outbound`{: .url } `Set domain outbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" +!!! api "`GET`{: .get } `/api/throttle//inbound`{: .url } `Get user inbound throttle settings`{: .comment }" +!!! api "`POST`{: .post } `/api/throttle//inbound`{: .url } `Set user inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" +!!! api "`GET`{: .get } `/api/throttle//outbound`{: .url } `Get user outbound throttle settings`{: .comment }" +!!! api "`POST`{: .post } `/api/throttle//outbound`{: .url } `Set user outbound throttle settings`{: .comment } `Parameters`{: .has_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) + +
+ + + + + + + + + + + + + + + diff --git a/html/css/markdown.css b/html/css/markdown.css index c2d13675..ceb618a3 100755 --- a/html/css/markdown.css +++ b/html/css/markdown.css @@ -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 */ diff --git a/html/iredadmin-pro.restful.api-new.html b/html/iredadmin-pro.restful.api-new.html deleted file mode 100644 index b243f99f..00000000 --- a/html/iredadmin-pro.restful.api-new.html +++ /dev/null @@ -1,516 +0,0 @@ - - - - iRedAdmin-Pro: RESTful API - - - - -

iRedAdmin-Pro: RESTful API

-
-

Note

-

If you need an API which has not yet been implemented, don't hesitate to -contact us.

-
-
- -
-

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/domain/<domain> POST Create a new domain

-
-
-

/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 NameSummarySample Usage
cnthe short description of this domain name. e.g. company namecn=iRedMail Project
quotaa integer number for mailbox quota (for whole domain, in MB)quota=20480
languagedefault preferred language for new userlanguage=en_US
defaultQuotadefault mailbox quota for new userdefaultQuota=1024
maxUserQuotaMax mailbox quota of a single mail usermaxUserQuota=2048
numberOfUsersMax number of mail user accountsnumberOfUsers=20
numberOfAliasesMax number of mail alias accountsnumberOfAliases=30
-
-

User

-
-

/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 of all mail user under domain

-
-
-

/api/users/<domain>/password PUT Update passwords of all users under domain

-

Required parameter:

- - - - - - - - - - - - - -
Parameter NameSample Usage
passwordpassword=Ww0nXVEV8iv4ap@p4b
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
URLHTTP MethodSummary
/api/user/<mail>POSTCreate a new mail user
/api/user/<mail>DELETEDelete an existing mail user
/api/user/<mail>PUTUpdate profile of an existing mail user
/api/users/<domain>PUTUpdate profiles for all users under domain <domain>
/api/users/<domain>/passwordPUTUpdate passwords of all users under domain <domain>
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
cndisplay namecn=John Smith
accountStatusAccount statusaccountStatus=disabled (or active)
languagedefault preferred language for new userlanguage=en_US
transportTransport programtransport=dovecot
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
accountStatusAccount statusaccountStatus=disabled (or active)
languagedefault preferred language for new userlanguage=en_US
transportTransport programtransport=dovecot
-

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

- - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
passwordUpdate passwords of all users under domainpassword=Ww0nXVEV8iv4ap@p4b
-

Mailing List

-
-

Note

-

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

-
- - - - - - - - - - - - - - - - - - - - - - - - - -
URLHTTP MethodSummary
/api/maillist/<mail>POSTCreate a new mailing list
/api/maillist/<mail>DELETEDelete an existing mailing list
/api/maillist/<mail>PUTUpdate profile of an existing mailing list
-

Possible PUT parameters used to update account profile:

- - - - - - - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
cndisplay namecn=My List Name
accessPolicyDefines who can send email to this mailing listaccessPolicy=public
-

Mail Alias

- - - - - - - - - - - - - - - - - - - - - - - - - -
URLHTTP MethodSummary
/api/alias/<mail>POSTCreate a new mail alias
/api/alias/<mail>DELETEDelete an existing mail alias
/api/alias/<mail>PUTUpdate profile of an existing mail alias
-

Possible PUT parameters used to update account profile:

- - - - - - - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
cndisplay namecn=My List Name
accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
-
-

Note: accessPolicy for mail alias account is only available for SQL backends.

-
-

Throttling

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
URLHTTP MethodSummary
/api/throttle/global/inboundGETGet global inbound throttle settings
/api/throttle/global/outboundGETGet global outbound throttle settings
/api/throttle/global/inboundPOSTSet global inbound throttle setting
/api/throttle/global/outboundPOSTSet global outbound throttle setting
/api/throttle/<domain>/inboundGETGet domain inbound throttle settings
/api/throttle/<domain>/outboundGETGet domain outbound throttle settings
/api/throttle/<domain>/inboundPOSTSet domain inbound throttle setting
/api/throttle/<domain>/outboundPOSTSet domain outbound throttle setting
/api/throttle/<mail>/inboundGETGet user inbound throttle settings
/api/throttle/<mail>/outboundGETGet user outbound throttle settings
/api/throttle/<mail>/inboundPOSTSet user inbound throttle setting
/api/throttle/<mail>/outboundPOSTSet user outbound throttle setting
-

Possible POST parameters used to set throttle setting:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Parameter NameSummarySample Usage
periodPeriod of time (in seconds)period=3600 (one hour)
msg_sizeMax size of single emailmsg_size=10485760 (10 MB)
max_msgsNumber of max inbound emailsmax_msgs=20 (up to 20 messages)
max_quotaCumulative size of all inbound emailsmax_quota=1048576000 (1 GB)
-

Sample code to interact with iRedAdmin-Pro RESTful API

-

All documents are available in BitBucket repository, and published under Creative Commons license. If you found something wrong, please do contact us to fix it. - \ No newline at end of file diff --git a/html/iredadmin-pro.restful.api.html b/html/iredadmin-pro.restful.api.html index 9ca00d31..6653bd39 100644 --- a/html/iredadmin-pro.restful.api.html +++ b/html/iredadmin-pro.restful.api.html @@ -26,6 +26,7 @@

  • Summary
  • Requirements
  • Enable RESTful API
    • +
  • Sample code to interact with iRedAdmin-Pro RESTful API
  • APIs
    • -
  • Sample code to interact with iRedAdmin-Pro RESTful API
    • @@ -42,8 +42,8 @@

    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>'}.
      • +
    • If operation succeed, iRedAdmin-Pro returns JSON data: {'success': true}.
      • +
    • If operation failed, iRedAdmin-Pro returns JSON data: {'success': false, 'msg': '<error_reason>'}.

    Requirements

      @@ -66,40 +66,28 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]

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

      +

      Sample code to interact with iRedAdmin-Pro RESTful API

      +

      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.
      -

      Domain

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      URLHTTP MethodSummary
      /api/domain/<domain>POSTCreate a new domin
      /api/domain/<domain>DELETEDelete an existing domain
      /api/domain/<domain>PUTUpdate profile of an existing domain
      -

      Possible PUT parameters used to update account profile:

      +

      +

      Domain

      + + +
      +

      POST /api/domain/<domain> Create a new domain Parameters

      +
      + @@ -111,27 +99,27 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...] - - + + - - + + - - + + - + - + @@ -144,36 +132,49 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...] - -
      cnthe short description of this domain name. e.g. company namecn=iRedMail ProjectShort description of this domain name. e.g. company namecn=Google Inc
      quotaa integer number for mailbox quota (for whole domain, in MB)quota=20480Mailbox quota for whole domain, in MB.quota=2048
      preferredLanguagedefault preferred language for new userlanguageDefault preferred language for newly created mail user preferredLanguage=en_US
      defaultQuotadefault mailbox quota for new userDefault per-user mailbox quota for newly created user defaultQuota=1024
      maxUserQuotaMax mailbox quota of a single mail userMax mailbox quota of a mail user maxUserQuota=2048
      Max number of mail alias accounts numberOfAliases=30
      -

      User

      - - - - - - - - - - - - - - - - - - - - - - + + +
      URLHTTP MethodSummary
      /api/user/<mail>POSTCreate a new mail user
      /api/user/<mail>DELETEDelete an existing mail user
      /api/user/<mail>PUTUpdate profile of an existing mail usernumberOfListsMax number of mailing list accounts (LDAP only)numberOfLists=40
      -

      Possible PUT parameters used to update account profile:

      +
      + +
      +
      +

      DELETE /api/domain/<domain> Delete an existing domain

      +
      + + +

      User

      +
      +

      POST /api/user/<mail> Create a new mail user

      +
      +
      +

      DELETE /api/user/<mail> Delete an existing mail user

      +
      +
      +

      PUT /api/user/<mail> Update profile of an existing mail user Parameters

      +
      + @@ -185,64 +186,116 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...] - + - - + + - + - - - - -
      cndisplay nameDisplay name cn=My New Name
      preferredLanguagedefault preferred language for new userlanguagePreferred language of web UI preferredLanguage=en_US
      mailQuotamailbox quota for this user (in MB)User's mailbox quota, in MB mailQuota=1024
      passwordPasswordpassword=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.

      + +
      +
      +

      PUT /api/user/<mail>/password Update user's password upcoming Parameters

      +
      + - - - + + - - - - - - - - - - - - - + +
      URLHTTP MethodSummaryParameter NameComment
      /api/maillist/<mail>POSTCreate a new mailing list
      /api/maillist/<mail>DELETEDelete an existing mailing list
      /api/maillist/<mail>PUTUpdate profile of an existing mailing listpasswordPassword
      -

      Possible PUT parameters used to update account profile:

      +
      + +
      +
      +

      PUT /api/users/<domain> Update profiles of all users under domain upcoming Parameters

      +
      + + + + + + + + + + + + + + + + + + + + + + +
      Parameter NameComment
      accountStatusAccount status. Possible value is: active, disabled.
      languagePreferred language of web UI
      transportPer-user transport
      +
      + +
      +
      +

      PUT /api/users/<domain>/password Update passwords of all users under domain upcoming Parameters

      +
      + + + + + + + + + + + + + + +
      Parameter NameComment
      passwordPassword
      +
      + +
      +

      Mailing List

      +
      +

      Attention

      +

      Mailing list is only available in OpenLDAP backend. For SQL backends, +please use mail alias account as mailing list.

      +
      +
      +

      POST /api/maillist/<mail> Create a new mailing list

      +
      +
      +

      DELETE /api/maillist/<mail> Delete an existing mailing list

      +
      +
      +

      PUT /api/maillist/<mail> Update profile of an existing mailing list Parameters

      +
      + @@ -264,34 +317,20 @@ account as mailing list.

      -

      Mail Alias

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      URLHTTP MethodSummary
      /api/alias/<mail>POSTCreate a new mail alias
      /api/alias/<mail>DELETEDelete an existing mail alias
      /api/alias/<mail>PUTUpdate profile of an existing mail alias
      -

      Possible PUT parameters used to update account profile:

      +
      + +
      +

      Mail Alias

      +
      +

      POST /api/alias/<mail> Create a new mail alias

      +
      +
      +

      DELETE /api/alias/<mail> Delete an existing mail alias

      +
      +
      +

      PUT /api/alias/<mail> Update profile of an existing mail alias Parameters

      +
      + @@ -316,79 +355,48 @@ account as mailing list.

      Note: accessPolicy for mail alias account is only available for SQL backends.

      -

      Throttling

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      URLHTTP MethodSummary
      /api/throttle/global/inboundGETGet global inbound throttle settings
      /api/throttle/global/outboundGETGet global outbound throttle settings
      /api/throttle/global/inboundPOSTSet global inbound throttle setting
      /api/throttle/global/outboundPOSTSet global outbound throttle setting
      /api/throttle/<domain>/inboundGETGet domain inbound throttle settings
      /api/throttle/<domain>/outboundGETGet domain outbound throttle settings
      /api/throttle/<domain>/inboundPOSTSet domain inbound throttle setting
      /api/throttle/<domain>/outboundPOSTSet domain outbound throttle setting
      /api/throttle/<mail>/inboundGETGet user inbound throttle settings
      /api/throttle/<mail>/outboundGETGet user outbound throttle settings
      /api/throttle/<mail>/inboundPOSTSet user inbound throttle setting
      /api/throttle/<mail>/outboundPOSTSet user outbound throttle setting
      -

      Possible POST parameters used to set throttle setting:

      +
      + +
      +

      Throttling

      +
      +

      GET /api/throttle/global/inbound Get global inbound throttle settings

      +
      +
      +

      POST /api/throttle/global/inbound Set global inbound throttle settings Parameters

      +
      +
      +

      GET /api/throttle/global/outbound Get global outbound throttle settings

      +
      +
      +

      POST /api/throttle/global/outbound Set global inbound throttle settings Parameters

      +
      +
      +

      GET /api/throttle/<domain>/inbound Get domain inbound throttle settings

      +
      +
      +

      POST /api/throttle/<domain>/inbound Set domain inbound throttle settings Parameters

      +
      +
      +

      GET /api/throttle/<domain>/outbound Get domain outbound throttle settings

      +
      +
      +

      POST /api/throttle/<domain>/outbound Set domain outbound throttle settings Parameters

      +
      +
      +

      GET /api/throttle/<mail>/inbound Get user inbound throttle settings

      +
      +
      +

      POST /api/throttle/<mail>/inbound Set user inbound throttle settings Parameters

      +
      +
      +

      GET /api/throttle/<mail>/outbound Get user outbound throttle settings

      +
      +
      +

      POST /api/throttle/<mail>/outbound Set user outbound throttle settings Parameters

      +
      + +

      Parameters available for global, per-domain, per-user throttle settings.

      @@ -399,13 +407,13 @@ account as mailing list.

      - - + + - + @@ -415,16 +423,38 @@ account as mailing list.

      - +
      periodPeriod of time (in seconds)period *Period of time, in seconds period=3600 (one hour)
      msg_sizeMax size of single emailMax size of single email, in bytes msg_size=10485760 (10 MB)
      max_quotaCumulative size of all inbound emailsCumulative size of inbound or outbound emails, in bytes max_quota=1048576000 (1 GB)
      -

      Sample code to interact with iRedAdmin-Pro RESTful API

      -

      All documents are available in BitBucket repository, and published under Creative Commons license. If you found something wrong, please do contact us to fix it. + +

      All documents are available in BitBucket repository, and published under Creative Commons license. If you found something wrong, please do contact us to fix it.