2016-04-18 09:34:43 -05:00
< 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" >
2016-04-19 12:48:51 -05:00
< 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 >
2016-04-18 09:34:43 -05:00
// < a href = "./index.html" > Document Index< / a > < / div > < h1 id = "iredadmin-pro-restful-api" > iRedAdmin-Pro: RESTful API< / h1 >
2016-04-20 05:23:37 -05:00
< 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 >
2016-04-18 09:34:43 -05:00
< 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 >
2016-04-21 10:42:39 -05:00
< li > < a href = "#enable-restful-api" > Enable RESTful API< / a > < / li >
2016-04-18 09:34:43 -05:00
< li > < a href = "#apis" > APIs< / a > < ul >
< li > < a href = "#domain" > Domain< / a > < / li >
< li > < a href = "#user" > User< / a > < / li >
2016-04-20 02:11:50 -05:00
< li > < a href = "#mailing-list" > Mailing List< / a > < / li >
2016-04-18 09:34:43 -05:00
< li > < a href = "#mail-alias" > Mail Alias< / a > < / li >
2016-04-20 05:23:37 -05:00
< li > < a href = "#throttling" > Throttling< / a > < / li >
2016-04-18 09:34:43 -05:00
< / ul >
< / li >
< li > < a href = "#sample-code-to-interact-with-iredadmin-pro-restful-api" > Sample code to interact with iRedAdmin-Pro RESTful API< / a > < / li >
< / ul >
< / li >
< / ul >
< / div >
< h2 id = "summary" > Summary< / h2 >
< p > iRedAdmin-Pro RESTful API will return message in JSON format.< / p >
< ul >
2016-04-21 23:33:25 -05:00
< li > If operation succeed, client will receive JSON data: < code > {'success': true}< / code > .< / li >
< li > If operation failed, client will receive JSON data: < code > {'success': false, 'msg': '< error_reason> '}< / code > .< / li >
2016-04-18 09:34:43 -05:00
< / 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 >
2016-04-21 10:42:39 -05:00
< h2 id = "enable-restful-api" > Enable RESTful API< / h2 >
< p > RESTful API is disabled by default, to enable it, please add setting below in
iRedAdmin-Pro config file < code > settings.py< / code > :< / p >
< pre > < code > ENABLE_RESTFUL_API = True
< / code > < / pre >
< p > To restrict API access to few IP addresses, please also add settings below in
iRedAdmin-Pro config file:< / p >
< pre > < code > # Enable restriction
RESTRICT_API_ACCESS = True
# List all IP addresses of allowed client for API access.
RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
< / code > < / pre >
< p > Restarting Apache or uwsgi (if you're running Nginx) is required.< / p >
2016-04-18 09:34:43 -05:00
< 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 >
2016-04-20 02:11:50 -05:00
< tr >
< td > < code > password< / code > < / td >
< td > Password< / td >
< td > < code > password=Ww0nXVEV8iv4ap@p4b< / code > < / td >
< / tr >
< tr >
< td > < code > transport< / code > < / td >
< td > Transport program< / td >
< td > < code > transport=dovecot< / code > < / td >
< / tr >
2016-04-18 09:34:43 -05:00
< / tbody >
< / table >
2016-04-20 02:11:50 -05:00
< h3 id = "mailing-list" > Mailing List< / h3 >
< div class = "admonition note" >
< p class = "admonition-title" > Note< / p >
< p > This is applicable to OpenLDAP. For SQL backends, please use mail alias
account as mailing list.< / p >
< / div >
2016-04-18 09:34:43 -05:00
< 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 >
2016-04-20 02:11:50 -05:00
< tr >
< td > < code > accessPolicy< / code > < / td >
2016-04-20 11:08:59 -05:00
< td > Defines who can send email to this mailing list< / td >
2016-04-20 02:11:50 -05:00
< td > < code > accessPolicy=public< / code > < / td >
< / tr >
2016-04-18 09:34:43 -05:00
< / 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 >
2016-04-20 02:11:50 -05:00
< tr >
< td > < code > accessPolicy< / code > < / td >
2016-04-20 11:08:59 -05:00
< td > Defines who can send email to this mail alias account< / td >
2016-04-20 02:11:50 -05:00
< td > < code > accessPolicy=public< / code > < / td >
< / tr >
2016-04-18 09:34:43 -05:00
< / tbody >
< / table >
2016-04-20 02:11:50 -05:00
< blockquote >
2016-05-04 11:43:04 -05:00
< p > Note: < code > accessPolicy< / code > for mail alias account is only available for SQL backends.< / p >
2016-04-20 02:11:50 -05:00
< / blockquote >
2016-04-20 05:23:37 -05:00
< h3 id = "throttling" > Throttling< / h3 >
< table >
< thead >
< tr >
< th > URL< / th >
< th > HTTP Method< / th >
< th > Summary< / th >
< / tr >
< / thead >
< tbody >
< tr >
2016-04-20 11:08:59 -05:00
< td > /api/throttle/global/inbound< / td >
2016-04-20 05:23:37 -05:00
< td > GET< / td >
2016-04-20 11:08:59 -05:00
< td > Get global inbound throttle settings< / td >
2016-04-20 05:23:37 -05:00
< / tr >
< tr >
2016-04-20 11:08:59 -05:00
< td > /api/throttle/global/outbound< / td >
< td > GET< / td >
< td > Get global outbound throttle settings< / td >
< / tr >
< tr >
< td > /api/throttle/global/inbound< / td >
2016-04-20 05:23:37 -05:00
< td > POST< / td >
< td > Set global inbound throttle setting< / td >
< / tr >
< tr >
2016-04-20 11:08:59 -05:00
< td > /api/throttle/global/outbound< / td >
2016-04-20 05:23:37 -05:00
< td > POST< / td >
< td > Set global outbound throttle setting< / td >
< / tr >
2016-04-20 11:08:59 -05:00
< tr >
< td > /api/throttle/< domain>/inbound< / td >
< td > GET< / td >
< td > Get domain inbound throttle settings< / td >
< / tr >
< tr >
< td > /api/throttle/< domain>/outbound< / td >
< td > GET< / td >
< td > Get domain outbound throttle settings< / td >
< / tr >
< tr >
< td > /api/throttle/< domain>/inbound< / td >
< td > POST< / td >
< td > Set domain inbound throttle setting< / td >
< / tr >
< tr >
< td > /api/throttle/< domain>/outbound< / td >
< td > POST< / td >
< td > Set domain outbound throttle setting< / td >
< / tr >
< tr >
< td > /api/throttle/< mail>/inbound< / td >
< td > GET< / td >
< td > Get user inbound throttle settings< / td >
< / tr >
< tr >
< td > /api/throttle/< mail>/outbound< / td >
< td > GET< / td >
< td > Get user outbound throttle settings< / td >
< / tr >
< tr >
< td > /api/throttle/< mail>/inbound< / td >
< td > POST< / td >
< td > Set user inbound throttle setting< / td >
< / tr >
< tr >
< td > /api/throttle/< mail>/outbound< / td >
< td > POST< / td >
< td > Set user outbound throttle setting< / td >
< / tr >
2016-04-20 05:23:37 -05:00
< / tbody >
< / table >
2016-04-20 11:08:59 -05:00
< p > Possible < code > POST< / code > parameters used to set throttle setting:< / p >
2016-04-20 05:23:37 -05:00
< table >
< thead >
< tr >
< th > Parameter Name< / th >
< th > Summary< / th >
< th > Sample Usage< / th >
< / tr >
< / thead >
< tbody >
< tr >
< td > < code > period< / code > < / td >
< td > Period of time (in seconds)< / td >
< td > < code > period=3600< / code > (one hour)< / td >
< / tr >
< tr >
< td > < code > msg_size< / code > < / td >
< td > Max size of single email< / td >
< td > < code > msg_size=10485760< / code > (10 MB)< / td >
< / tr >
< tr >
< td > < code > max_msgs< / code > < / td >
< td > Number of max inbound emails< / td >
< td > < code > max_msgs=20< / code > (up to 20 messages)< / td >
< / tr >
< tr >
< td > < code > max_quota< / code > < / td >
< td > Cumulative size of all inbound emails< / td >
< td > < code > max_quota=1048576000< / code > (1 GB)< / td >
< / tr >
< / tbody >
< / table >
2016-04-18 09:34:43 -05:00
< 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 >