New: iredadmin-pro.restful.api.curl.html, iredadmin-pro.restful.api.python.html.
This commit is contained in:
Zhang Huangbin
parent
d6313738e5
commit
c2f01688e6
|
|
@ -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': '<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
|
||||
|
||||
* [iRedAdmin-Pro RESTful API (interact with Python)](./iredadmin-pro.restful.api.python.html)
|
||||
|
|
@ -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': '<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
|
||||
|
||||
!!! 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
|
||||
|
||||
* [iRedAdmin-Pro RESTful API (interact with `curl`)](./iredadmin-pro.restful.api.curl.html)
|
||||
|
|
@ -172,6 +172,8 @@
|
|||
<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.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>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,116 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>iRedAdmin-Pro RESTful API (interact 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="#login">Login</a></li>
|
||||
<li><a href="#domain">Domain</a><ul>
|
||||
<li><a href="#create-a-new-mail-domain">Create a new mail domain</a></li>
|
||||
<li><a href="#delete-an-existing-mail-domain">Delete an existing mail domain</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#user">User</a><ul>
|
||||
<li><a href="#create-a-new-mail-user">Create a new mail user</a></li>
|
||||
<li><a href="#delete-an-existing-mail-user">Delete an existing mail user</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#see-also">See Also</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</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>
|
||||
<li>Our samples below requires tool <code>curl</code>: <a href="https://curl.haxx.se">https://curl.haxx.se</a>.</li>
|
||||
</ul>
|
||||
<h2 id="login">Login</h2>
|
||||
<pre><code>curl -X POST -c cookie.txt -d "username=<username>&password=<password>" https://<server>/api/login
|
||||
</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>
|
||||
<h2 id="domain">Domain</h2>
|
||||
<h3 id="create-a-new-mail-domain">Create a new mail domain</h3>
|
||||
<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>
|
||||
<h3 id="delete-an-existing-mail-domain">Delete an existing mail domain</h3>
|
||||
<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>
|
||||
<h2 id="user">User</h2>
|
||||
<h3 id="create-a-new-mail-user">Create a new mail user</h3>
|
||||
<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>
|
||||
<h3 id="delete-an-existing-mail-user">Delete an existing mail user</h3>
|
||||
<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>
|
||||
<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>
|
||||
</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>
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>iRedAdmin-Pro RESTful API (interact 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</a></li>
|
||||
<li><a href="#create-new-domain">Create new domain</a></li>
|
||||
<li><a href="#delete-domain">Delete domain</a></li>
|
||||
<li><a href="#create-new-user">Create new user</a></li>
|
||||
<li><a href="#delete-user">Delete user</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#see-also">See Also</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</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>
|
||||
<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</h3>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>We need the cookies for further operations.</p>
|
||||
</div>
|
||||
<pre><code>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
|
||||
</code></pre>
|
||||
|
||||
<h3 id="create-new-domain">Create new domain</h3>
|
||||
<p>Create new domain <code>test.com</code>.</p>
|
||||
<pre><code>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>
|
||||
<h3 id="delete-domain">Delete domain</h3>
|
||||
<p>Delete domain: test.com</p>
|
||||
<pre><code>requests.delete(url + '/domain/test.com', cookies=cookies)
|
||||
</code></pre>
|
||||
|
||||
<h3 id="create-new-user">Create new user</h3>
|
||||
<p>Create new user <code>zhb@test.com</code>.</p>
|
||||
<pre><code>requests.post(url + '/user/zhb@test.com',
|
||||
cookies=cookies,
|
||||
data={'cn': 'Zhang Huangbin',
|
||||
'password': 'password_for_zhb',
|
||||
'preferredLanguage': 'en_US',
|
||||
'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>
|
||||
<h3 id="delete-user">Delete user</h3>
|
||||
<p>Delete user <code>zhb@test.com</code></p>
|
||||
<pre><code>requests.delete(url + '/user/zhb@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>
|
||||
</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>
|
||||
Loading…
Reference in New Issue