diff --git a/en_US/faq/2-iredadmin-pro.restful.api.curl.md b/en_US/faq/2-iredadmin-pro.restful.api.curl.md new file mode 100644 index 00000000..1b128df9 --- /dev/null +++ b/en_US/faq/2-iredadmin-pro.restful.api.curl.md @@ -0,0 +1,86 @@ +# iRedAdmin-Pro RESTful API (interact with `curl`) + +[TOC] + +## Summary + +iRedAdmin-Pro RESTful API will return message in JSON format. + +* If operation succeed, it returns JSON `{'success': true}`. +* If operation failed, it returns JSON `{'success': false, 'msg': ''}`. + +## Requirements + +* At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases + didn't offer RESTful API. +* Our samples below requires tool `curl`: . + +## Login + +``` +curl -X POST -c cookie.txt -d "username=&password=" https:///api/login +``` + +* Replace `` by the real admin email address. +* Replace `` by the real admin password. +* It will create a plain text file `cookie.txt` under current directory. + +## Domain + +### Create a new mail domain + +``` +curl -X POST -i -b cookie.txt -d "var=&var2=value2" https:///api/domain/ +``` + +* Replace `` by the (new) real domain name. + +Optional POST data: + +* `cn`: the short description of this domain name. e.g. company name. +* `quota`: a integer number for mailbox quota (for whole domain) +* `preferredLanguage`: default preferred language for new user. e.g. `en_US` for English, `de_DE` for Deutsch. +* `defaultQuota`: default mailbox quota for new user. +* `maxUserQuota`: Max mailbox quota of a single mail user +* `numberOfUsers`: Max number of mail user accounts +* `numberOfAliases`: Max number of mail alias accounts + +### Delete an existing mail domain + +``` +curl -X DELETE -i -b cookie.txt https:///api/domain/ +``` + +* Replace `` by the (existing) domain name. + +## User + +### Create a new mail user + +``` +curl -X POST -i -b cookie.txt -d "var=value1&var2=value2&..." https:///api/user/ +``` + +* Replace `` by the (new) email address. + +Required POST data: + +* `password`: password for this user + +Optional POST data: + +* `cn`: display name +* `preferredLanguage`: default preferred language for new user. e.g. `en_US` for English, `de_DE` for Deutsch. +* `mailQuota`: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited. + +### Delete an existing mail user + +``` +curl -X DELETE -i -b cookie.txt https:///api/user/ +``` + +* Replace `` by the (existing) email address. + +## See Also + +* [iRedAdmin-Pro RESTful API (interact with Python)](./iredadmin-pro.restful.api.python.html) diff --git a/en_US/faq/2-iredadmin-pro.restful.api.python.md b/en_US/faq/2-iredadmin-pro.restful.api.python.md new file mode 100644 index 00000000..ffe3006b --- /dev/null +++ b/en_US/faq/2-iredadmin-pro.restful.api.python.md @@ -0,0 +1,113 @@ +# iRedAdmin-Pro RESTful API (interact with Python) + +[TOC] + +## Summary + +iRedAdmin-Pro RESTful API will return message in JSON format. + +* If operation succeed, it returns JSON `{'success': true}`. +* If operation failed, it returns JSON `{'success': false, 'msg': ''}`. + +## Requirements + +* At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases + didn't offer RESTful API. +* Our sample Python code requires Python module `requests`. For more details, + please read its [official documentation](http://docs.python-requests.org/en/master/). + +## Sample code + +### Login + +!!! note + + We need the cookies for further operations. + +``` +import sys +import requests + +# Base URL to iRedAdmin-Pro API interface +url = 'https:///iredadmin/api' + +# Admin username (email) and password. +admin = 'my_admin@domain.com' +pw = 'my_password' + +# +# Login +# +r = requests.post(url + '/login', data={'username': admin, 'password': pw}) + +# Get returned JSON data (Python dict) +data = r.json() +if not data['success']: + sys.exit('Login failed') + +# Get cookies +cookies = r.cookies +``` + +### Create new domain + +Create new domain `test.com`. + +``` +requests.post(url + '/domain/test.com', + cookies=cookies, + data={'defaultQuota': '1024'}) +``` + +Optional POST data: + +* `cn`: the short description of this domain name. e.g. company name. +* `quota`: a integer number for mailbox quota (for whole domain) +* `preferredLanguage`: default preferred language for new user. e.g. `en_US` for English, `de_DE` for Deutsch. +* `defaultQuota`: default mailbox quota for new user. +* `maxUserQuota`: Max mailbox quota of a single mail user +* `numberOfUsers`: Max number of mail user accounts +* `numberOfAliases`: Max number of mail alias accounts + +### Delete domain + +Delete domain: test.com + +``` +requests.delete(url + '/domain/test.com', cookies=cookies) +``` + +### Create new user + +Create new user `zhb@test.com`. + +``` +requests.post(url + '/user/zhb@test.com', + cookies=cookies, + data={'cn': 'Zhang Huangbin', + 'password': 'password_for_zhb', + 'preferredLanguage': 'en_US', + 'mailQuota': 2048}) +``` + +Required POST data: + +* `password`: password for this user + +Optional POST data: + +* `cn`: display name +* `preferredLanguage`: default preferred language for new user. e.g. `en_US` for English, `de_DE` for Deutsch. +* `mailQuota`: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited. + +### Delete user + +Delete user `zhb@test.com` + +``` +requests.delete(url + '/user/zhb@test.com', cookies=cookies) +``` + +## See Also + +* [iRedAdmin-Pro RESTful API (interact with `curl`)](./iredadmin-pro.restful.api.curl.html) diff --git a/html/index.html b/html/index.html index 7da54857..6c4d6121 100644 --- a/html/index.html +++ b/html/index.html @@ -172,6 +172,8 @@
  • Errors you may see while maintaining iRedMail server
  • Why append timestamp in maildir path
  • iRedAdmin-Pro: Default password restrictions
    • +
  • iRedAdmin-Pro RESTful API (interact with curl)
    • +
  • iRedAdmin-Pro RESTful API (interact with Python)
  • iRedAdmin-Pro: Enable self-service to allow users to manage their own preferences and more
  • iRedAdmin-Pro: Translate iRedAdmin to your local language
  • Explanation of Amavisd SQL database
    • diff --git a/html/iredadmin-pro.restful.api.curl.html b/html/iredadmin-pro.restful.api.curl.html new file mode 100644 index 00000000..430b3b32 --- /dev/null +++ b/html/iredadmin-pro.restful.api.curl.html @@ -0,0 +1,116 @@ + + + + iRedAdmin-Pro RESTful API (interact with `curl`) + + + + +

    iRedAdmin-Pro RESTful API (interact with curl)

    +
    + +
    +

    Summary

    +

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

    +
      +
    • If operation succeed, it returns JSON {'success': true}.
      • +
    • If operation failed, it returns JSON {'success': false, 'msg': '<error_reason>'}.
      • +
    +

    Requirements

    +
      +
    • At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases + didn't offer RESTful API.
      • +
    • Our samples below requires tool curl: https://curl.haxx.se.
      • +
    +

    Login

    +
    curl -X POST -c cookie.txt -d "username=<username>&password=<password>" https://<server>/api/login
+
    + +
      +
    • Replace <username> by the real admin email address.
      • +
    • Replace <password> by the real admin password.
      • +
    • It will create a plain text file cookie.txt under current directory.
      • +
    +

    Domain

    +

    Create a new mail domain

    +
    curl -X POST -i -b cookie.txt -d "var=<value>&var2=value2" https://<server>/api/domain/<domain>
+
    + +
      +
    • Replace <domain> by the (new) real domain name.
      • +
    +

    Optional POST data:

    +
      +
    • cn: the short description of this domain name. e.g. company name.
      • +
    • quota: a integer number for mailbox quota (for whole domain)
      • +
    • preferredLanguage: default preferred language for new user. e.g. en_US for English, de_DE for Deutsch.
      • +
    • defaultQuota: default mailbox quota for new user.
      • +
    • maxUserQuota: Max mailbox quota of a single mail user
      • +
    • numberOfUsers: Max number of mail user accounts
      • +
    • numberOfAliases: Max number of mail alias accounts
      • +
    +

    Delete an existing mail domain

    +
    curl -X DELETE -i -b cookie.txt https://<server>/api/domain/<domain>
+
    + +
      +
    • Replace <domain> by the (existing) domain name.
      • +
    +

    User

    +

    Create a new mail user

    +
    curl -X POST -i -b cookie.txt -d "var=value1&var2=value2&..." https://<server>/api/user/<mail>
+
    + +
      +
    • Replace <mail> by the (new) email address.
      • +
    +

    Required POST data:

    +
      +
    • password: password for this user
      • +
    +

    Optional POST data:

    +
      +
    • cn: display name
      • +
    • preferredLanguage: default preferred language for new user. e.g. en_US for English, de_DE for Deutsch.
      • +
    • mailQuota: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited.
      • +
    +

    Delete an existing mail user

    +
    curl -X DELETE -i -b cookie.txt https://<server>/api/user/<mail>
+
    + +
      +
    • Replace <mail> by the (existing) email address.
      • +
    +

    See Also

    +

    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.python.html b/html/iredadmin-pro.restful.api.python.html new file mode 100644 index 00000000..0f5f00c3 --- /dev/null +++ b/html/iredadmin-pro.restful.api.python.html @@ -0,0 +1,132 @@ + + + + iRedAdmin-Pro RESTful API (interact with Python) + + + + +

    iRedAdmin-Pro RESTful API (interact with Python)

    +
    + +
    +

    Summary

    +

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

    +
      +
    • If operation succeed, it returns JSON {'success': true}.
      • +
    • If operation failed, it returns JSON {'success': false, 'msg': '<error_reason>'}.
      • +
    +

    Requirements

    +
      +
    • At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases + didn't offer RESTful API.
      • +
    • Our sample Python code requires Python module requests. For more details, + please read its official documentation.
      • +
    +

    Sample code

    +

    Login

    +
    +

    Note

    +

    We need the cookies for further operations.

    +
    +
    import sys
+import requests
+
+# Base URL to iRedAdmin-Pro API interface
+url = 'https://<server>/iredadmin/api'
+
+# Admin username (email) and password.
+admin = 'my_admin@domain.com'
+pw = 'my_password'
+
+#
+# Login
+#
+r = requests.post(url + '/login', data={'username': admin, 'password': pw})
+
+# Get returned JSON data (Python dict)
+data = r.json()
+if not data['success']:
+    sys.exit('Login failed')
+
+# Get cookies
+cookies = r.cookies
+
    + +

    Create new domain

    +

    Create new domain test.com.

    +
    requests.post(url + '/domain/test.com',
+              cookies=cookies,
+              data={'defaultQuota': '1024'})
+
    + +

    Optional POST data:

    +
      +
    • cn: the short description of this domain name. e.g. company name.
      • +
    • quota: a integer number for mailbox quota (for whole domain)
      • +
    • preferredLanguage: default preferred language for new user. e.g. en_US for English, de_DE for Deutsch.
      • +
    • defaultQuota: default mailbox quota for new user.
      • +
    • maxUserQuota: Max mailbox quota of a single mail user
      • +
    • numberOfUsers: Max number of mail user accounts
      • +
    • numberOfAliases: Max number of mail alias accounts
      • +
    +

    Delete domain

    +

    Delete domain: test.com

    +
    requests.delete(url + '/domain/test.com', cookies=cookies)
+
    + +

    Create new user

    +

    Create new user zhb@test.com.

    +
    requests.post(url + '/user/zhb@test.com',
+              cookies=cookies,
+              data={'cn': 'Zhang Huangbin',
+                    'password': 'password_for_zhb',
+                    'preferredLanguage': 'en_US',
+                    'mailQuota': 2048})
+
    + +

    Required POST data:

    +
      +
    • password: password for this user
      • +
    +

    Optional POST data:

    +
      +
    • cn: display name
      • +
    • preferredLanguage: default preferred language for new user. e.g. en_US for English, de_DE for Deutsch.
      • +
    • mailQuota: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited.
      • +
    +

    Delete user

    +

    Delete user zhb@test.com

    +
    requests.delete(url + '/user/zhb@test.com', cookies=cookies)
+
    + +

    See Also

    +

    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