Organize docs (iredadmin restful api).
This commit is contained in:
Zhang Huangbin
parent
ea8ce97d09
commit
7de73c0db2
|
|
@ -0,0 +1,83 @@
|
|||
# Interact iRedAdmin-Pro RESTful API with `curl`
|
||||
|
||||
!!! note
|
||||
|
||||
* For more details about iRedAdmin-Pro RESTful API, please read document:
|
||||
[iRedAdmin-Pro: RESTful API](./iredadmin-pro.restful.api.html).
|
||||
* If you need an API which has not yet been implemented, don't hesitate to
|
||||
[contact us](../contact.html).
|
||||
* Our sample code below requires thiard-party Python module `requests`. For
|
||||
more details, please read its official documentation:
|
||||
[Requests: HTTP for Humans](http://docs.python-requests.org/en/master/)
|
||||
|
||||
Sample `curl` commands to interact iRedAdmin-Pro RESTful API.
|
||||
|
||||
* replace `<server>` in url by the real server address (hostname or IP) which
|
||||
runs iRedAdmin-Pro (with the `/iredadmin` prefix). for example,
|
||||
`https://my_domain.com/iredadmin`.
|
||||
* replace `<domain>` in url by the real domain name.
|
||||
* replace `<mail>` in url by the real email address.
|
||||
|
||||
```
|
||||
#
|
||||
# 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.
|
||||
curl -X POST -c cookie.txt -d "username=<username>&password=<password>" https://<server>/api/login
|
||||
|
||||
#
|
||||
# Create domain (POST)
|
||||
#
|
||||
# cn=ABC Inc. (display name: "ABC Inc."
|
||||
# quota=20480 (quota: 20 GB)
|
||||
curl -X POST -i -b cookie.txt -d "cn=ABC Inc."a=20480" https://<server>/api/domain/<domain>
|
||||
|
||||
#
|
||||
# Create mail user (POST)
|
||||
#
|
||||
# cn=Zhang Huangbin (display name: "Zhang Huangbin")
|
||||
# mailQuota=1024 (mailbox quota: 1 GB)
|
||||
curl -X POST -i -b cookie.txt -d "cn=Zhang Huangbin&mailQuota=1024" https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Delete mail user (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Update mail user profiles (PUT)
|
||||
#
|
||||
curl -X PUT -i -b cookie.txt -d "cn=John Smith&mailQuota=2048" https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Create mail alias (POST)
|
||||
#
|
||||
# cn=My Alias (display name: "My Alias")
|
||||
curl -X POST -i -b cookie.txt -d "cn=My Alias" https://<server>/api/alias/<mail>
|
||||
|
||||
#
|
||||
# Delete mail alias (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/alias/<mail>
|
||||
|
||||
#
|
||||
# Create mailing list (POST, OpenLDAP backend only)
|
||||
#
|
||||
curl -X POST -i -b cookie.txt -d "cn=My List" https://<server>/api/maillist/<mail>
|
||||
|
||||
#
|
||||
# Delete mail alias (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/maillist/<mail>
|
||||
|
||||
#
|
||||
# Delete domain (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/domain/<domain>
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
* [Interact iRedAdmin-Pro RESTful API with Python](./iredadmin-pro.restful.api.python.html)
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
# Interact iRedAdmin-Pro RESTful API with Python
|
||||
|
||||
!!! note
|
||||
|
||||
* For more details about iRedAdmin-Pro RESTful API, please read document:
|
||||
[iRedAdmin-Pro: RESTful API](./iredadmin-pro.restful.api.html).
|
||||
* If you need an API which has not yet been implemented, don't hesitate to
|
||||
[contact us](../contact.html).
|
||||
* Our sample code below requires thiard-party Python module `requests`. For
|
||||
more details, please read its official documentation:
|
||||
[Requests: HTTP for Humans](http://docs.python-requests.org/en/master/)
|
||||
|
||||
Sample Python code to interact iRedAdmin-Pro RESTful API.
|
||||
|
||||
```
|
||||
import sys
|
||||
import requests
|
||||
|
||||
url = 'http://<server>/iredadmin/api'
|
||||
|
||||
# Admin email address and password.
|
||||
admin = 'postmaster@mydomain.com'
|
||||
pw = 'my_password'
|
||||
|
||||
# Login
|
||||
r = requests.post(url + '/login', data={'username': admin,
|
||||
'password': pw})
|
||||
|
||||
# Get returned JSON data and get auth_token.
|
||||
data = r.json()
|
||||
if data['success']:
|
||||
auth_token = r.text['auth_token']
|
||||
else:
|
||||
sys.exit('Login failed')
|
||||
|
||||
cookies = r.cookies
|
||||
|
||||
# Create domain: test.com
|
||||
requests.post(url + '/domain/test.com',
|
||||
cookies=cookies,
|
||||
data={'defaultQuota': '1024'})
|
||||
|
||||
# Create user: zhb@test.com
|
||||
requests.post(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Name',
|
||||
'password': '1@Password',
|
||||
'preferredLanguage': 'zh_CN',
|
||||
'mailQuota': 2048})
|
||||
|
||||
# Create list: list@test.com. Note: OpenLDAP only.
|
||||
requests.post(url + '/maillist/list@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My List'})
|
||||
|
||||
# Create alias: alias@test.com
|
||||
requests.post(url + '/alias/alias@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Alias'})
|
||||
|
||||
# Update user: zhb@test.com
|
||||
requests.put(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My New Name',
|
||||
'password': 'WHDZ2@5yxORvVqzYY',
|
||||
'transport': 'dovecot',
|
||||
'language': 'en_US',
|
||||
'quota': 2048})
|
||||
|
||||
# Delete user: zhb@test.com
|
||||
requests.delete(url + '/user/zhb@test.com', cookies=cookies)
|
||||
|
||||
# Delete mailing list: list@test.com. Note: OpenLDAP only.
|
||||
requests.delete(url + '/maillist/list@test.com', cookies=cookies)
|
||||
|
||||
# Delete alias: alias@test.com
|
||||
requests.delete(url + '/alias/alias@test.com', cookies=cookies)
|
||||
|
||||
# Delete domain: test.com
|
||||
requests.delete(url + '/domain/test.com', cookies=cookies)
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
* [Interact iRedAdmin-Pro RESTful API with `curl`](./iredadmin-pro.restful.api.curl.html)
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
# iRedAdmin-Pro RESTful API (interact with `curl`)
|
||||
|
||||
[TOC]
|
||||
|
||||
!!! note
|
||||
|
||||
If you need an API which has not yet been implemented, feel free to
|
||||
[contact us](../contact.html).
|
||||
|
||||
## 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>.
|
||||
|
||||
## Samples
|
||||
|
||||
### Login (`/login`, POST)
|
||||
|
||||
```
|
||||
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 (`/domain/<domain>`)
|
||||
|
||||
#### Create domain (POST)
|
||||
|
||||
```
|
||||
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 domain (DELETE)
|
||||
|
||||
```
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/domain/<domain>
|
||||
```
|
||||
|
||||
* Replace `<domain>` by the (existing) domain name.
|
||||
|
||||
### Mail User (`/user/<mail>`)
|
||||
|
||||
#### Create mail user (POST)
|
||||
|
||||
```
|
||||
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 mail user (DELETE)
|
||||
|
||||
```
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/user/<mail>
|
||||
```
|
||||
|
||||
* Replace `<mail>` by the (existing) email address.
|
||||
|
||||
#### Update mail user profiles (PUT)
|
||||
|
||||
```
|
||||
curl -X PUT -i -b cookie.txt -d "var=<value>&var2=<value2>" https://<server>/api/user/<mail>
|
||||
```
|
||||
|
||||
Optional PUT data:
|
||||
|
||||
* `name`: display name.
|
||||
* `accountStatus`: enable or disable user. possible value is: active, disabled.
|
||||
* `password`: set new password for user
|
||||
* `quota`: set mailbox quota (in MB)
|
||||
* `language`: set preferred language of web UI
|
||||
* `transport`: set per-user transport
|
||||
|
||||
### Mail Alias (`/alias/<mail>`)
|
||||
|
||||
#### Create mail alias (POST)
|
||||
|
||||
```
|
||||
curl -X POST -i -b cookie.txt -d "..." https://<server>/api/alias/<mail>
|
||||
```
|
||||
|
||||
* Replace `<mail>` by the email address of (new) mail alias account.
|
||||
|
||||
Optional POST data:
|
||||
|
||||
* `cn`: display name
|
||||
|
||||
#### Delete mail alias (DELETE)
|
||||
|
||||
```
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/alias/<mail>
|
||||
```
|
||||
|
||||
* Replace `<mail>` by the email address (existing) mail alias account.
|
||||
|
||||
### Mailing List (`/maillist/<mail>`, OpenLDAP backend only)
|
||||
|
||||
#### Create mailing list (POST)
|
||||
|
||||
```
|
||||
curl -X POST -i -b cookie.txt -d "..." https://<server>/api/maillist/<mail>
|
||||
```
|
||||
|
||||
* Replace `<mail>` by the email address of (new) mailing list.
|
||||
|
||||
Optional POST data:
|
||||
|
||||
* `cn`: display name
|
||||
|
||||
#### Delete mail alias (DELETE)
|
||||
|
||||
```
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/maillist/<mail>
|
||||
```
|
||||
|
||||
* Replace `<mail>` by the email address of (existing) mailing list.
|
||||
|
||||
## See Also
|
||||
|
||||
* [iRedAdmin-Pro RESTful API (interact with Python)](./iredadmin-pro.restful.api.python.html)
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
# iRedAdmin-Pro: RESTful API
|
||||
|
||||
[TOC]
|
||||
|
||||
!!! note
|
||||
|
||||
If you need an API which has not yet been implemented, don't hesitate to
|
||||
[contact us](../contact.html).
|
||||
|
||||
## 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.
|
||||
|
||||
## 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`
|
||||
|
||||
### Mailing List (OpenLDAP only)
|
||||
|
||||
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`
|
||||
|
||||
### 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`
|
||||
|
||||
## 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)
|
||||
|
|
@ -1,176 +0,0 @@
|
|||
# iRedAdmin-Pro RESTful API (interact with Python)
|
||||
|
||||
[TOC]
|
||||
|
||||
!!! note
|
||||
|
||||
If you need an API which has not yet been implemented, feel free to
|
||||
[contact us](../contact.html).
|
||||
|
||||
## 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](http://docs.python-requests.org/en/master/).
|
||||
|
||||
## Sample code
|
||||
|
||||
### Login (`/login`, POST)
|
||||
|
||||
!!! 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
|
||||
```
|
||||
|
||||
### Domain (`/domain/<domain>`)
|
||||
#### Create domain (POST)
|
||||
|
||||
Create 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)
|
||||
|
||||
```
|
||||
requests.delete(url + '/domain/test.com', cookies=cookies)
|
||||
```
|
||||
|
||||
### Mail User (`/user/<mail>`)
|
||||
|
||||
#### Create mail user (POST)
|
||||
|
||||
Create mail 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 mail user (DELETE)
|
||||
|
||||
```
|
||||
requests.delete(url + '/user/zhb@test.com', cookies=cookies)
|
||||
```
|
||||
|
||||
#### Update mail user profiles (PUT)
|
||||
|
||||
```
|
||||
requests.put(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'password': '<a_strong_password>'})
|
||||
```
|
||||
|
||||
Optional PUT data:
|
||||
|
||||
* `name`: display name.
|
||||
* `accountStatus`: enable or disable user. possible value is: active, disabled.
|
||||
* `password`: set new password for user
|
||||
* `quota`: set mailbox quota (in MB)
|
||||
* `language`: set preferred language of web UI
|
||||
* `transport`: set per-user transport
|
||||
|
||||
### Mail Alias (`/alias/<mail>`)
|
||||
|
||||
#### Create mail alias (POST)
|
||||
|
||||
Create mail alias account `alias@test.com`.
|
||||
|
||||
```
|
||||
requests.post(url + '/alias/alias@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Alias'})
|
||||
```
|
||||
|
||||
Optional POST data:
|
||||
|
||||
* `cn`: display name
|
||||
|
||||
#### Delete mail alias (DELETE)
|
||||
|
||||
```
|
||||
requests.delete(url + '/alias/alias@test.com', cookies=cookies)
|
||||
```
|
||||
|
||||
### Mailing List (`/maillist/<mail>`, OpenLDAP backend only)
|
||||
|
||||
#### Create mailing list (POST)
|
||||
|
||||
```
|
||||
requests.post(url + '/maillist/list@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Mailing List'})
|
||||
```
|
||||
|
||||
Optional POST data:
|
||||
|
||||
* `cn`: display name
|
||||
|
||||
#### Delete mail alias (DELETE)
|
||||
|
||||
```
|
||||
requests.delete(url + '/maillist/list@test.com', cookies=cookies)
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
* [iRedAdmin-Pro RESTful API (interact with `curl`)](./iredadmin-pro.restful.api.curl.html)
|
||||
|
|
@ -368,3 +368,12 @@ li { line-height: 26px; }
|
|||
.attention { background: #e7f2fa; }
|
||||
.warning { background: #FFFFE1; }
|
||||
.attention p { margin-top: 4px; }
|
||||
|
||||
/* Table */
|
||||
th { padding: 5px 10px 5px 10px; }
|
||||
td { padding: 0px 10px 0px 10px; }
|
||||
/*
|
||||
table { border: 1px solid black; }
|
||||
th, td { border: 1px solid black; }
|
||||
caption { font-size: 200%;}
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -172,8 +172,7 @@
|
|||
<li><a href="errors.html">Errors you may see while maintaining iRedMail server</a></li>
|
||||
<li><a href="why.append.timestamp.in.maildir.path.html">Why append timestamp in maildir path</a></li>
|
||||
<li><a href="iredadmin-pro.default.password.policy.html">iRedAdmin-Pro: Default password restrictions</a></li>
|
||||
<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>
|
||||
<li><a href="iredadmin-pro.restful.api.html">iRedAdmin-Pro: RESTful API</a></li>
|
||||
<li><a href="iredadmin-pro.self-service.html">iRedAdmin-Pro: Enable self-service to allow users to manage their own preferences and more</a></li>
|
||||
<li><a href="translate.iredadmin.html">iRedAdmin-Pro: Translate iRedAdmin to your local language</a></li>
|
||||
<li><a href="amavisd.sql.db.html">Explanation of Amavisd SQL database</a></li>
|
||||
|
|
|
|||
|
|
@ -1,180 +1,96 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>iRedAdmin-Pro RESTful API (interact with `curl`)</title>
|
||||
<title>Interact iRedAdmin-Pro RESTful API with `curl`</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;"/> <span>iRedMail</span></a>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="iredadmin-pro-restful-api-interact-with-curl">iRedAdmin-Pro RESTful API (interact with <code>curl</code>)</h1>
|
||||
<div class="toc">
|
||||
<ul>
|
||||
<li><a href="#iredadmin-pro-restful-api-interact-with-curl">iRedAdmin-Pro RESTful API (interact with curl)</a><ul>
|
||||
<li><a href="#summary">Summary</a></li>
|
||||
<li><a href="#requirements">Requirements</a></li>
|
||||
<li><a href="#samples">Samples</a><ul>
|
||||
<li><a href="#login-login-post">Login (/login, POST)</a></li>
|
||||
<li><a href="#domain-domaindomain">Domain (/domain/<domain>)</a><ul>
|
||||
<li><a href="#create-domain-post">Create domain (POST)</a></li>
|
||||
<li><a href="#delete-domain-delete">Delete domain (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mail-user-usermail">Mail User (/user/<mail>)</a><ul>
|
||||
<li><a href="#create-mail-user-post">Create mail user (POST)</a></li>
|
||||
<li><a href="#delete-mail-user-delete">Delete mail user (DELETE)</a></li>
|
||||
<li><a href="#update-mail-user-profiles-put">Update mail user profiles (PUT)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mail-alias-aliasmail">Mail Alias (/alias/<mail>)</a><ul>
|
||||
<li><a href="#create-mail-alias-post">Create mail alias (POST)</a></li>
|
||||
<li><a href="#delete-mail-alias-delete">Delete mail alias (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mailing-list-maillistmail-openldap-backend-only">Mailing List (/maillist/<mail>, OpenLDAP backend only)</a><ul>
|
||||
<li><a href="#create-mailing-list-post">Create mailing list (POST)</a></li>
|
||||
<li><a href="#delete-mail-alias-delete_1">Delete mail alias (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#see-also">See Also</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="interact-iredadmin-pro-restful-api-with-curl">Interact iRedAdmin-Pro RESTful API with <code>curl</code></h1>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>If you need an API which has not yet been implemented, feel free to
|
||||
<a href="../contact.html">contact us</a>.</p>
|
||||
<ul>
|
||||
<li>For more details about iRedAdmin-Pro RESTful API, please read document:
|
||||
<a href="./iredadmin-pro.restful.api.html">iRedAdmin-Pro: RESTful API</a>.</li>
|
||||
<li>If you need an API which has not yet been implemented, don't hesitate to
|
||||
<a href="../contact.html">contact us</a>.</li>
|
||||
<li>Our sample code below requires thiard-party Python module <code>requests</code>. For
|
||||
more details, please read its official documentation:
|
||||
<a href="http://docs.python-requests.org/en/master/">Requests: HTTP for Humans</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<h2 id="summary">Summary</h2>
|
||||
<p>iRedAdmin-Pro RESTful API will return message in JSON format.</p>
|
||||
<p>Sample <code>curl</code> commands to interact iRedAdmin-Pro RESTful API.</p>
|
||||
<ul>
|
||||
<li>If operation succeed, it returns JSON <code>{'success': true}</code>.</li>
|
||||
<li>If operation failed, it returns JSON <code>{'success': false, 'msg': '<error_reason>'}</code>.</li>
|
||||
<li>replace <code><server></code> in url by the real server address (hostname or IP) which
|
||||
runs iRedAdmin-Pro (with the <code>/iredadmin</code> prefix). for example,
|
||||
<code>https://my_domain.com/iredadmin</code>.</li>
|
||||
<li>replace <code><domain></code> in url by the real domain name.</li>
|
||||
<li>replace <code><mail></code> in url by the real email address.</li>
|
||||
</ul>
|
||||
<h2 id="requirements">Requirements</h2>
|
||||
<ul>
|
||||
<li>At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases
|
||||
didn't offer RESTful API.</li>
|
||||
<li>Our samples below requires tool <code>curl</code>: <a href="https://curl.haxx.se">https://curl.haxx.se</a>.</li>
|
||||
</ul>
|
||||
<h2 id="samples">Samples</h2>
|
||||
<h3 id="login-login-post">Login (<code>/login</code>, POST)</h3>
|
||||
<pre><code>curl -X POST -c cookie.txt -d "username=<username>&password=<password>" https://<server>/api/login
|
||||
<pre><code>#
|
||||
# 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.
|
||||
curl -X POST -c cookie.txt -d "username=<username>&password=<password>" https://<server>/api/login
|
||||
|
||||
#
|
||||
# Create domain (POST)
|
||||
#
|
||||
# cn=ABC Inc. (display name: "ABC Inc."
|
||||
# quota=20480 (quota: 20 GB)
|
||||
curl -X POST -i -b cookie.txt -d "cn=ABC Inc.&quota=20480" https://<server>/api/domain/<domain>
|
||||
|
||||
#
|
||||
# Create mail user (POST)
|
||||
#
|
||||
# cn=Zhang Huangbin (display name: "Zhang Huangbin")
|
||||
# mailQuota=1024 (mailbox quota: 1 GB)
|
||||
curl -X POST -i -b cookie.txt -d "cn=Zhang Huangbin&mailQuota=1024" https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Delete mail user (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Update mail user profiles (PUT)
|
||||
#
|
||||
curl -X PUT -i -b cookie.txt -d "cn=John Smith&mailQuota=2048" https://<server>/api/user/<mail>
|
||||
|
||||
#
|
||||
# Create mail alias (POST)
|
||||
#
|
||||
# cn=My Alias (display name: "My Alias")
|
||||
curl -X POST -i -b cookie.txt -d "cn=My Alias" https://<server>/api/alias/<mail>
|
||||
|
||||
#
|
||||
# Delete mail alias (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/alias/<mail>
|
||||
|
||||
#
|
||||
# Create mailing list (POST, OpenLDAP backend only)
|
||||
#
|
||||
curl -X POST -i -b cookie.txt -d "cn=My List" https://<server>/api/maillist/<mail>
|
||||
|
||||
#
|
||||
# Delete mail alias (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/maillist/<mail>
|
||||
|
||||
#
|
||||
# Delete domain (DELETE)
|
||||
#
|
||||
curl -X DELETE -i -b cookie.txt https://<server>/api/domain/<domain>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><username></code> by the real admin email address.</li>
|
||||
<li>Replace <code><password></code> by the real admin password.</li>
|
||||
<li>It will create a plain text file <code>cookie.txt</code> under current directory.</li>
|
||||
</ul>
|
||||
<h3 id="domain-domaindomain">Domain (<code>/domain/<domain></code>)</h3>
|
||||
<h4 id="create-domain-post">Create domain (POST)</h4>
|
||||
<pre><code>curl -X POST -i -b cookie.txt -d "var=<value>&var2=value2" https://<server>/api/domain/<domain>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><domain></code> by the (new) real domain name.</li>
|
||||
</ul>
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: the short description of this domain name. e.g. company name.</li>
|
||||
<li><code>quota</code>: a integer number for mailbox quota (for whole domain)</li>
|
||||
<li><code>preferredLanguage</code>: default preferred language for new user. e.g. <code>en_US</code> for English, <code>de_DE</code> for Deutsch.</li>
|
||||
<li><code>defaultQuota</code>: default mailbox quota for new user.</li>
|
||||
<li><code>maxUserQuota</code>: Max mailbox quota of a single mail user</li>
|
||||
<li><code>numberOfUsers</code>: Max number of mail user accounts</li>
|
||||
<li><code>numberOfAliases</code>: Max number of mail alias accounts</li>
|
||||
</ul>
|
||||
<h4 id="delete-domain-delete">Delete domain (DELETE)</h4>
|
||||
<pre><code>curl -X DELETE -i -b cookie.txt https://<server>/api/domain/<domain>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><domain></code> by the (existing) domain name.</li>
|
||||
</ul>
|
||||
<h3 id="mail-user-usermail">Mail User (<code>/user/<mail></code>)</h3>
|
||||
<h4 id="create-mail-user-post">Create mail user (POST)</h4>
|
||||
<pre><code>curl -X POST -i -b cookie.txt -d "var=value1&var2=value2&..." https://<server>/api/user/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the (new) email address.</li>
|
||||
</ul>
|
||||
<p>Required POST data:</p>
|
||||
<ul>
|
||||
<li><code>password</code>: password for this user</li>
|
||||
</ul>
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
<li><code>preferredLanguage</code>: default preferred language for new user. e.g. <code>en_US</code> for English, <code>de_DE</code> for Deutsch.</li>
|
||||
<li><code>mailQuota</code>: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited.</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-user-delete">Delete mail user (DELETE)</h4>
|
||||
<pre><code>curl -X DELETE -i -b cookie.txt https://<server>/api/user/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the (existing) email address.</li>
|
||||
</ul>
|
||||
<h4 id="update-mail-user-profiles-put">Update mail user profiles (PUT)</h4>
|
||||
<pre><code>curl -X PUT -i -b cookie.txt -d "var=<value>&var2=<value2>" https://<server>/api/user/<mail>
|
||||
</code></pre>
|
||||
|
||||
<p>Optional PUT data:</p>
|
||||
<ul>
|
||||
<li><code>name</code>: display name.</li>
|
||||
<li><code>accountStatus</code>: enable or disable user. possible value is: active, disabled.</li>
|
||||
<li><code>password</code>: set new password for user</li>
|
||||
<li><code>quota</code>: set mailbox quota (in MB)</li>
|
||||
<li><code>language</code>: set preferred language of web UI</li>
|
||||
<li><code>transport</code>: set per-user transport</li>
|
||||
</ul>
|
||||
<h3 id="mail-alias-aliasmail">Mail Alias (<code>/alias/<mail></code>)</h3>
|
||||
<h4 id="create-mail-alias-post">Create mail alias (POST)</h4>
|
||||
<pre><code>curl -X POST -i -b cookie.txt -d "..." https://<server>/api/alias/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the email address of (new) mail alias account.</li>
|
||||
</ul>
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-alias-delete">Delete mail alias (DELETE)</h4>
|
||||
<pre><code>curl -X DELETE -i -b cookie.txt https://<server>/api/alias/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the email address (existing) mail alias account.</li>
|
||||
</ul>
|
||||
<h3 id="mailing-list-maillistmail-openldap-backend-only">Mailing List (<code>/maillist/<mail></code>, OpenLDAP backend only)</h3>
|
||||
<h4 id="create-mailing-list-post">Create mailing list (POST)</h4>
|
||||
<pre><code>curl -X POST -i -b cookie.txt -d "..." https://<server>/api/maillist/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the email address of (new) mailing list.</li>
|
||||
</ul>
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-alias-delete_1">Delete mail alias (DELETE)</h4>
|
||||
<pre><code>curl -X DELETE -i -b cookie.txt https://<server>/api/maillist/<mail>
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>Replace <code><mail></code> by the email address of (existing) mailing list.</li>
|
||||
</ul>
|
||||
<h2 id="see-also">See Also</h2>
|
||||
<ul>
|
||||
<li><a href="./iredadmin-pro.restful.api.python.html">iRedAdmin-Pro RESTful API (interact with Python)</a></li>
|
||||
<li><a href="./iredadmin-pro.restful.api.python.html">Interact iRedAdmin-Pro RESTful API 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),
|
||||
|
|
|
|||
|
|
@ -0,0 +1,280 @@
|
|||
<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;"/> <span>iRedMail</span></a>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="iredadmin-pro-restful-api">iRedAdmin-Pro: RESTful API</h1>
|
||||
<div class="toc">
|
||||
<ul>
|
||||
<li><a href="#iredadmin-pro-restful-api">iRedAdmin-Pro: RESTful API</a><ul>
|
||||
<li><a href="#summary">Summary</a></li>
|
||||
<li><a href="#requirements">Requirements</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-openldap-only">Mailing List (OpenLDAP only)</a></li>
|
||||
<li><a href="#mail-alias">Mail Alias</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>
|
||||
<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>
|
||||
<h2 id="summary">Summary</h2>
|
||||
<p>iRedAdmin-Pro RESTful API will return message in JSON format.</p>
|
||||
<ul>
|
||||
<li>If operation succeed, it returns JSON <code>{'success': true}</code>.</li>
|
||||
<li>If operation failed, it returns JSON <code>{'success': false, 'msg': '<error_reason>'}</code>.</li>
|
||||
</ul>
|
||||
<h2 id="requirements">Requirements</h2>
|
||||
<ul>
|
||||
<li>At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases
|
||||
didn't offer RESTful API.</li>
|
||||
</ul>
|
||||
<h2 id="apis">APIs</h2>
|
||||
<p>Notes:</p>
|
||||
<ul>
|
||||
<li>replace <code><domain></code> in URL by the real domain name.</li>
|
||||
<li>replace <code><mail></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/<domain></td>
|
||||
<td>POST</td>
|
||||
<td>Create a new domin</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/domain/<domain></td>
|
||||
<td>DELETE</td>
|
||||
<td>Delete an existing domain</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/domain/<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>
|
||||
<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>preferredLanguage</code></td>
|
||||
<td>default preferred language for new 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><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>
|
||||
<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/<mail></td>
|
||||
<td>POST</td>
|
||||
<td>Create a new mail user</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/user/<mail></td>
|
||||
<td>DELETE</td>
|
||||
<td>Delete an existing mail user</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/user/<mail></td>
|
||||
<td>PUT</td>
|
||||
<td>Update profile of an existing mail user</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 New Name</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>preferredLanguage</code></td>
|
||||
<td>default preferred language for new user</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><code>mailQuota=1024</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="mailing-list-openldap-only">Mailing List (OpenLDAP only)</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>URL</th>
|
||||
<th>HTTP Method</th>
|
||||
<th>Summary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>/api/maillist/<mail></td>
|
||||
<td>POST</td>
|
||||
<td>Create a new mailing list</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/maillist/<mail></td>
|
||||
<td>DELETE</td>
|
||||
<td>Delete an existing mailing list</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/maillist/<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>
|
||||
</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/<mail></td>
|
||||
<td>POST</td>
|
||||
<td>Create a new mail alias</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/alias/<mail></td>
|
||||
<td>DELETE</td>
|
||||
<td>Delete an existing mail alias</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>/api/alias/<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>
|
||||
</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>
|
||||
|
|
@ -1,193 +1,97 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>iRedAdmin-Pro RESTful API (interact with Python)</title>
|
||||
<title>Interact iRedAdmin-Pro RESTful API with Python</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;"/> <span>iRedMail</span></a>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="iredadmin-pro-restful-api-interact-with-python">iRedAdmin-Pro RESTful API (interact with Python)</h1>
|
||||
<div class="toc">
|
||||
<ul>
|
||||
<li><a href="#iredadmin-pro-restful-api-interact-with-python">iRedAdmin-Pro RESTful API (interact with Python)</a><ul>
|
||||
<li><a href="#summary">Summary</a></li>
|
||||
<li><a href="#requirements">Requirements</a></li>
|
||||
<li><a href="#sample-code">Sample code</a><ul>
|
||||
<li><a href="#login-login-post">Login (/login, POST)</a></li>
|
||||
<li><a href="#domain-domaindomain">Domain (/domain/<domain>)</a><ul>
|
||||
<li><a href="#create-domain-post">Create domain (POST)</a></li>
|
||||
<li><a href="#delete-domain-delete">Delete domain (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mail-user-usermail">Mail User (/user/<mail>)</a><ul>
|
||||
<li><a href="#create-mail-user-post">Create mail user (POST)</a></li>
|
||||
<li><a href="#delete-mail-user-delete">Delete mail user (DELETE)</a></li>
|
||||
<li><a href="#update-mail-user-profiles-put">Update mail user profiles (PUT)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mail-alias-aliasmail">Mail Alias (/alias/<mail>)</a><ul>
|
||||
<li><a href="#create-mail-alias-post">Create mail alias (POST)</a></li>
|
||||
<li><a href="#delete-mail-alias-delete">Delete mail alias (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#mailing-list-maillistmail-openldap-backend-only">Mailing List (/maillist/<mail>, OpenLDAP backend only)</a><ul>
|
||||
<li><a href="#create-mailing-list-post">Create mailing list (POST)</a></li>
|
||||
<li><a href="#delete-mail-alias-delete_1">Delete mail alias (DELETE)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#see-also">See Also</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="interact-iredadmin-pro-restful-api-with-python">Interact iRedAdmin-Pro RESTful API with Python</h1>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>If you need an API which has not yet been implemented, feel free to
|
||||
<a href="../contact.html">contact us</a>.</p>
|
||||
</div>
|
||||
<h2 id="summary">Summary</h2>
|
||||
<p>iRedAdmin-Pro RESTful API will return message in JSON format.</p>
|
||||
<ul>
|
||||
<li>If operation succeed, it returns JSON <code>{'success': true}</code>.</li>
|
||||
<li>If operation failed, it returns JSON <code>{'success': false, 'msg': '<error_reason>'}</code>.</li>
|
||||
<li>For more details about iRedAdmin-Pro RESTful API, please read document:
|
||||
<a href="./iredadmin-pro.restful.api.html">iRedAdmin-Pro: RESTful API</a>.</li>
|
||||
<li>If you need an API which has not yet been implemented, don't hesitate to
|
||||
<a href="../contact.html">contact us</a>.</li>
|
||||
<li>Our sample code below requires thiard-party Python module <code>requests</code>. For
|
||||
more details, please read its official documentation:
|
||||
<a href="http://docs.python-requests.org/en/master/">Requests: HTTP for Humans</a></li>
|
||||
</ul>
|
||||
<h2 id="requirements">Requirements</h2>
|
||||
<ul>
|
||||
<li>At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases
|
||||
didn't offer RESTful API.</li>
|
||||
<li>Our sample Python code requires Python module <code>requests</code>. For more details,
|
||||
please read its <a href="http://docs.python-requests.org/en/master/">official documentation</a>.</li>
|
||||
</ul>
|
||||
<h2 id="sample-code">Sample code</h2>
|
||||
<h3 id="login-login-post">Login (<code>/login</code>, POST)</h3>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>We need the cookies for further operations.</p>
|
||||
</div>
|
||||
<p>Sample Python code to interact iRedAdmin-Pro RESTful API.</p>
|
||||
<pre><code>import sys
|
||||
import requests
|
||||
|
||||
# Base URL to iRedAdmin-Pro API interface
|
||||
url = 'https://<server>/iredadmin/api'
|
||||
url = 'http://<server>/iredadmin/api'
|
||||
|
||||
# Admin username (email) and password.
|
||||
admin = 'my_admin@domain.com'
|
||||
# Admin email address and password.
|
||||
admin = 'postmaster@mydomain.com'
|
||||
pw = 'my_password'
|
||||
|
||||
#
|
||||
# Login
|
||||
#
|
||||
r = requests.post(url + '/login', data={'username': admin, 'password': pw})
|
||||
r = requests.post(url + '/login', data={'username': admin,
|
||||
'password': pw})
|
||||
|
||||
# Get returned JSON data (Python dict)
|
||||
# Get returned JSON data and get auth_token.
|
||||
data = r.json()
|
||||
if not data['success']:
|
||||
if data['success']:
|
||||
auth_token = r.text['auth_token']
|
||||
else:
|
||||
sys.exit('Login failed')
|
||||
|
||||
# Get cookies
|
||||
cookies = r.cookies
|
||||
</code></pre>
|
||||
|
||||
<h3 id="domain-domaindomain">Domain (<code>/domain/<domain></code>)</h3>
|
||||
<h4 id="create-domain-post">Create domain (POST)</h4>
|
||||
<p>Create domain <code>test.com</code>.</p>
|
||||
<pre><code>requests.post(url + '/domain/test.com',
|
||||
# Create domain: test.com
|
||||
requests.post(url + '/domain/test.com',
|
||||
cookies=cookies,
|
||||
data={'defaultQuota': '1024'})
|
||||
</code></pre>
|
||||
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: the short description of this domain name. e.g. company name.</li>
|
||||
<li><code>quota</code>: a integer number for mailbox quota (for whole domain)</li>
|
||||
<li><code>preferredLanguage</code>: default preferred language for new user. e.g. <code>en_US</code> for English, <code>de_DE</code> for Deutsch.</li>
|
||||
<li><code>defaultQuota</code>: default mailbox quota for new user.</li>
|
||||
<li><code>maxUserQuota</code>: Max mailbox quota of a single mail user</li>
|
||||
<li><code>numberOfUsers</code>: Max number of mail user accounts</li>
|
||||
<li><code>numberOfAliases</code>: Max number of mail alias accounts</li>
|
||||
</ul>
|
||||
<h4 id="delete-domain-delete">Delete domain (DELETE)</h4>
|
||||
<pre><code>requests.delete(url + '/domain/test.com', cookies=cookies)
|
||||
</code></pre>
|
||||
|
||||
<h3 id="mail-user-usermail">Mail User (<code>/user/<mail></code>)</h3>
|
||||
<h4 id="create-mail-user-post">Create mail user (POST)</h4>
|
||||
<p>Create mail user <code>zhb@test.com</code>.</p>
|
||||
<pre><code>requests.post(url + '/user/zhb@test.com',
|
||||
# Create user: zhb@test.com
|
||||
requests.post(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'Zhang Huangbin',
|
||||
'password': 'password_for_zhb',
|
||||
'preferredLanguage': 'en_US',
|
||||
data={'cn': 'My Name',
|
||||
'password': '1@Password',
|
||||
'preferredLanguage': 'zh_CN',
|
||||
'mailQuota': 2048})
|
||||
</code></pre>
|
||||
|
||||
<p>Required POST data:</p>
|
||||
<ul>
|
||||
<li><code>password</code>: password for this user</li>
|
||||
</ul>
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
<li><code>preferredLanguage</code>: default preferred language for new user. e.g. <code>en_US</code> for English, <code>de_DE</code> for Deutsch.</li>
|
||||
<li><code>mailQuota</code>: mailbox quota for this user (in MB). Defaults to per-domain quota setting or unlimited.</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-user-delete">Delete mail user (DELETE)</h4>
|
||||
<pre><code>requests.delete(url + '/user/zhb@test.com', cookies=cookies)
|
||||
</code></pre>
|
||||
# Create list: list@test.com. Note: OpenLDAP only.
|
||||
requests.post(url + '/maillist/list@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My List'})
|
||||
|
||||
<h4 id="update-mail-user-profiles-put">Update mail user profiles (PUT)</h4>
|
||||
<pre><code>requests.put(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'password': '<a_strong_password>'})
|
||||
</code></pre>
|
||||
|
||||
<p>Optional PUT data:</p>
|
||||
<ul>
|
||||
<li><code>name</code>: display name.</li>
|
||||
<li><code>accountStatus</code>: enable or disable user. possible value is: active, disabled.</li>
|
||||
<li><code>password</code>: set new password for user</li>
|
||||
<li><code>quota</code>: set mailbox quota (in MB)</li>
|
||||
<li><code>language</code>: set preferred language of web UI</li>
|
||||
<li><code>transport</code>: set per-user transport</li>
|
||||
</ul>
|
||||
<h3 id="mail-alias-aliasmail">Mail Alias (<code>/alias/<mail></code>)</h3>
|
||||
<h4 id="create-mail-alias-post">Create mail alias (POST)</h4>
|
||||
<p>Create mail alias account <code>alias@test.com</code>.</p>
|
||||
<pre><code>requests.post(url + '/alias/alias@test.com',
|
||||
# Create alias: alias@test.com
|
||||
requests.post(url + '/alias/alias@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Alias'})
|
||||
</code></pre>
|
||||
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-alias-delete">Delete mail alias (DELETE)</h4>
|
||||
<pre><code>requests.delete(url + '/alias/alias@test.com', cookies=cookies)
|
||||
</code></pre>
|
||||
# Update user: zhb@test.com
|
||||
requests.put(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My New Name',
|
||||
'password': 'WHDZ2@5yxORvVqzYY',
|
||||
'transport': 'dovecot',
|
||||
'language': 'en_US',
|
||||
'quota': 2048})
|
||||
|
||||
<h3 id="mailing-list-maillistmail-openldap-backend-only">Mailing List (<code>/maillist/<mail></code>, OpenLDAP backend only)</h3>
|
||||
<h4 id="create-mailing-list-post">Create mailing list (POST)</h4>
|
||||
<pre><code>requests.post(url + '/maillist/list@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'My Mailing List'})
|
||||
</code></pre>
|
||||
# Delete user: zhb@test.com
|
||||
requests.delete(url + '/user/zhb@test.com', cookies=cookies)
|
||||
|
||||
<p>Optional POST data:</p>
|
||||
<ul>
|
||||
<li><code>cn</code>: display name</li>
|
||||
</ul>
|
||||
<h4 id="delete-mail-alias-delete_1">Delete mail alias (DELETE)</h4>
|
||||
<pre><code>requests.delete(url + '/maillist/list@test.com', cookies=cookies)
|
||||
# Delete mailing list: list@test.com. Note: OpenLDAP only.
|
||||
requests.delete(url + '/maillist/list@test.com', cookies=cookies)
|
||||
|
||||
# Delete alias: alias@test.com
|
||||
requests.delete(url + '/alias/alias@test.com', cookies=cookies)
|
||||
|
||||
# Delete domain: test.com
|
||||
requests.delete(url + '/domain/test.com', cookies=cookies)
|
||||
</code></pre>
|
||||
|
||||
<h2 id="see-also">See Also</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.curl.html">Interact iRedAdmin-Pro RESTful API with <code>curl</code></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),
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ import web
|
|||
import markdown
|
||||
|
||||
# Markdown extensions
|
||||
MD_EXTENSIONS = ['toc', 'meta', 'extra', 'footnotes', 'admonition']
|
||||
MD_EXTENSIONS = ['toc', 'meta', 'extra', 'footnotes', 'admonition', 'tables']
|
||||
|
||||
# Get file name
|
||||
filename = sys.argv[1]
|
||||
|
|
|
|||
Loading…
Reference in New Issue