From f9e366ead8a3f749cac74516b47a5ab3c528b36d Mon Sep 17 00:00:00 2001 From: Zhang Huangbin Date: Thu, 24 Aug 2017 16:11:12 +0800 Subject: [PATCH] Update iRedAdmin-Pro restful api doc. --- .../0-iredadmin-pro.restful.api.new.md | 686 ------- .../iredadmin/2-iredadmin-pro.restful.api.md | 68 +- html/iredadmin-pro.restful.api.html | 120 +- html/iredadmin-pro.restful.api.new.html | 1702 ----------------- html/iredadmin-pro.restful.api.upcoming.html | 1593 --------------- 5 files changed, 178 insertions(+), 3991 deletions(-) delete mode 100644 en_US/iredadmin/0-iredadmin-pro.restful.api.new.md delete mode 100644 html/iredadmin-pro.restful.api.new.html delete mode 100644 html/iredadmin-pro.restful.api.upcoming.html diff --git a/en_US/iredadmin/0-iredadmin-pro.restful.api.new.md b/en_US/iredadmin/0-iredadmin-pro.restful.api.new.md deleted file mode 100644 index ff8a6432..00000000 --- a/en_US/iredadmin/0-iredadmin-pro.restful.api.new.md +++ /dev/null @@ -1,686 +0,0 @@ -# iRedAdmin-Pro: RESTful API - -[TOC] - -!!! attention - - * This document is applicable to `iRedAdmin-Pro-SQL-2.8.0` and - `iRedAdmin-Pro-LDAP-3.0`. If you're running an old release, please - upgrade iRedAdmin-Pro to the latest release, or check - [document for old releases](./iredadmin-pro.releases.html). - * 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: - * For http `POST`, `DELETE`, `PUT` methods, it returns JSON data: `{'_success': true}`. - * For http `GET` method, it returns JSON data: `{'_success': true, '_data': }`. -* If operation failed, it returns JSON data: `{'_success': false, '_msg': ''}`. - -## Enable RESTful API - -RESTful API is disabled by default, to enable it, please add setting below in -iRedAdmin-Pro config file `settings.py`: - -``` -ENABLE_RESTFUL_API = True -``` - -Restarting Apache or uwsgi (if you're running Nginx) is required after changed -iRedAdmin config file. - -!!! note "iRedAdmin-Pro config file location" - - * on RHEL/CentOS, it's `/var/www/iredadmin/settings.py`. - * on Debian/Ubuntu, it's `/opt/www/iredadmin/settings.py` (in recent iRedMail releases) or `/usr/share/apache2/iredadmin/settings.py` (in old iRedMail releases). - * on FreeBSD, it's `/usr/local/www/iredadmin/settings.py`. - * on OpenBSD, it's `/var/www/iredadmin/settings.py`. - -To restrict API access to few IP addresses, please also add settings below in -iRedAdmin-Pro config file: - -``` -# Enable restriction -RESTRICT_API_ACCESS = True - -# List all IP addresses of allowed client for API access. -RESTFUL_API_CLIENTS = ['172.16.244.1', ...] -``` - -## Sample code to interact with iRedAdmin-Pro RESTful API - -* [iRedAdmin-Pro RESTful API (interact with `curl`)](./iredadmin-pro.restful.api.curl.html) -* [iRedAdmin-Pro RESTful API (interact with Python)](./iredadmin-pro.restful.api.python.html) - -## APIs - -Notes: - -* Parameter name with a `*` mark means the parameter is required, otherwise is optional. -* replace `` in URL by the real domain name. e.g. `example.com` -* replace `` in URL by the real email address. e.g. `user@domain.com` -* replace `` in URL by an integer number. e.g. `30`, `200` - - - -### Login {: .toggle } - -!!! api "`POST`{: .post } `/api/login`{: .url } `Login with an admin username (full email address) and password`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `username` | Admin username. Must be a full email address. | `username=admin@mydomain.com` - `password` | (Plain) admin password. | `password=AsTr0ng@` - -
- -### Domain {: .toggle } - -!!! api "`GET`{: .get } `/api/domains`{: .url } `Get profiles of all managed mail domains`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name_only` | Return only mail domain names | `name_only=yes` - `disabled_only` | Return only disabled mail domains | `disabled_only=yes` - -
- -!!! api "`GET`{: .get } `/api/domain/`{: .url } `Get profile of an existing domain`{: .comment }" -!!! api "`POST`{: .post } `/api/domain/`{: .url } `Create a new domain`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name`* | Short description of this domain name. e.g. company name | `name=Google Inc` - `quota` | Per-domain mailbox quota, in MB. | `quota=2048` - `language` | Default preferred language for newly created mail user | `language=en_US` - `transport` | Transport program | `transport=dovecot` - `defaultQuota` | Default per-user mailbox quota for newly created user, in MB. | `defaultQuota=1024` - `maxUserQuota` | Max mailbox quota of a mail user, in MB. | `maxUserQuota=2048` - `numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20` - `numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30` - `numberOfLists` | Max number of mailing list accounts (Available in LDAP backends)| `numberOfLists=40` - `senderBcc` | Per-domain sender bcc | `senderBcc=user@domain.com` - `recipientBcc` | Per-domain recipient bcc | `recipientBcc=user@domain.com` - -
- -!!! api "`DELETE`{: .delete } `/api/domain/`{: .url } `Delete an existing domain (all mail messages will NOT be removed)`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/domain//keep_mailbox_days/`{: .url } `Delete domain, and keep all mail messages for given days. Defaults to keep forever.`{: .comment }" -!!! api "`PUT`{: .put } `/api/domain/`{: .url } `Update profile of an existing domain`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Short description of this domain name. e.g. company name | `name=Google Inc` - `accountStatus` | Enable or disable domain. Possible values: `active`, `disabled`. | `accountStatus=active` - `quota` | Mailbox quota for whole domain, in MB. | `quota=2048` - `language` | Default preferred language for newly created mail user | `language=en_US` - `transport` | Transport program | `transport=dovecot` - `minPasswordLength` | Minimal password length | `minPasswordLength=8` - `maxPasswordLength` | Maximum password length | `minPasswordLength=20` - `defaultQuota` | Default per-user mailbox quota for newly created user | `defaultQuota=1024` - `maxUserQuota` | Max mailbox quota of a mail user | `maxUserQuota=2048` - `numberOfUsers` | Max number of mail user accounts | `numberOfUsers=20` - `numberOfAliases` | Max number of mail alias accounts | `numberOfAliases=30` - `senderBcc` | Per-domain sender bcc address | `senderBcc=user@domain.com` - `recipientBcc` | Per-domain recipient bcc address | `recipientBcc=user@domain.com` - `is_backupmx` | Mark domain as Backup MX. Must be used with parameter `primarymx`. Conflicts with parameter `transport`. | `is_backupmx=yes` (or `no`) - `primarymx` | Hostname or IP address of primary MX, smtp port number is optional. Must be used with parameter `is_backupmx`. Conflicts with parameter `transport`. | `primarymx=202.96.134.133`, `primarymx=[mail.iredmail.org]:25` - `catchall` | Per-domain catch-all account (a list of email addresses used to receive emails sent to non-existing addresses under same domain). Multiple addresses must be separated by comma. Set an empty value to disable catch-all support. | `catchall=user@domain.com,user2@domain.com` or `catchall=` (disable catch-all) - `outboundRelay` | Per-domain outbound relay. Set an empty value to disable outbound relay. | `outboundRelay=smtp:[192.168.1.2]:25` or `outboundRelay=` (disable outbound relay) - `enableService` | Enable new services. Multiple services must be separated by comma. Available services are listed below. | `enableService=self-service` - `disableService` | Disable existing services. Multiple services must be separated by comma. Available services are listed below. | `disableService=self-service` - `removeAllServices` | Disable all services (including mail service) | `removeAllServices=` (empty value) - `disableDomainProfile` | disable given domain profiles. Normal admin cannot view and update disabled profiles in domain profile page. Available domain profiles are listed below. | `disableDomainProfile=bcc,relay,aliases` - `enableDomainProfile` | enable given domain profiles. Normal admin can view and update disabled profiles in domain profile page. Available domain profiles are listed below. | `enableDomainProfile=bcc,relay,aliases` - `disableUserProfile` | disable given user profiles. Normal admin cannot view and update disabled profiles in user profile page. Available user profiles are listed below. | `disableUserProfile=bcc,relay,aliases` - `enableUserProfile` | enable given domain profiles. Normal admin can view and update disabled profiles in user profile page. Available user profiles are listed below. | `enableUserProfile=bcc,relay,aliases` - `disableUserPreference` | disable given user preferences in self-service page. Normal mail user cannot view and update disabled preferences. Available user preferences are listed below. | `disableUserPreference=forwarding,wblist` - `enableUserPreference` | disable given user preferences in self-service page. Normal mail user can view and update disabled preferences. Available user preferences are listed below. | `enableUserProfile=forwarding,wblist` - - Available mail services: - - Profile | Comment - --- |--- - self-service | Enable self-service for the mail domain. - mail | All mail services. (LDAP backends only) - domainalias | Alias domain support. (LDAP backends only) - senderbcc | Per-domain sender bcc. (LDAP backends only) - recipientbcc | Per-domain recipient bcc. (LDAP backends only) - - Available domain profiles: - - Profile | Comment - --- |--- - bcc | Per-domain sender bcc and recipient bcc - relay | Per-domain inbound relay and outbound relay - catchall | Per-domain catchall account - aliases | Alias domains - throttle | Per-domain inbound and outbound throttling - greylisting | Per-domain greylisting service - wblist | Per-domain whitelists and blacklists - spampolicy | Per-domain spam policy - backupmx | Backup MX - advanced | Some extra settings - - Available user profiles: - - Profile | Comment - --- |--- - bcc | Per-user sender bcc and recipient bcc - forwarding | Per-user mail forwarding addresses - relay | Per-user inbound relay and outbound relay - aliases | Per-user alias addresses - throttle | Per-user inbound and outbound throttling - greylisting | Per-user greylisting service - wblist | Per-user whitelists and blacklists - spampolicy | Per-user spam policy - - Available user preferences (self-service): - - Profile | Comment - --- |--- - personal_info | Name, time zone, preferred language of web UI - forwarding | Per-user mail forwarding addresses - wblist | Per-user whitelists and blacklists - quarantine | Manage quarantined mails - rcvd_mails | View basic info of received mails, and whitelist/blacklist mail sender directly. - spampolicy | Per-user spam policy - -
- -!!! api "`PUT`{: .put } `/api/domain/admins/`{: .url } `Manage normal domain admins.`{: .comment } `Parameters`{: .has_params }" - -
- - !!! attention - - Normal domain admin can only promote mail users under managed domains - to be a domain admin. - - Parameter | Summary | Sample Usage - --- |--- |--- - `addAdmin` | Add new domain admins. Multiple services must be separated by comma. | `addAdmin=one@domain.com,two@domain.com` - `removeAdmin` | Remove existing domain admins. Multiple services must be separated by comma. | `removeAdmin=one@domain.com,two@domain.com` - `removeAllAdmins` | Remove all existing domain admins. | `removeAllAdmins=` (empty value) - -
- -### Domain Admin {: .toggle } - -!!! attention - - * This is standalone domain admin account, not mail user with admin privileges. - * Only global admin can access these APIs. - -!!! api "`GET`{: .get } `/api/admin/`{: .url } `Get profile of an existing domain admin`{: .comment }" -!!! api "`POST`{: .post } `/api/admin/`{: .url } `Create a new domain admin`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My Admin Name` - `password` | Password| `password=AsTr0ng@` - `accountStatus` | Enable or disable account. Possible values: `active`, `disabled`. | `accountStatus=active` - `language` | Preferred language of iRedAdmin web UI | `language=en_US` - `isGlobalAdmin` | Mark this admin as global admin | `isGlobalAdmin=yes` - - Below parameters are used by normal domain admin (`isGlobalAdmin=no`). With `isGlobalAdmin=yes`, these parameters will be discarded. - - Parameter | Summary | Sample Usage - --- |--- |--- - `maxDomains` | how many mail domains this admin can create | `maxDomains=5` - `maxQuota` | how much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter `quotaUnit`. Sample: 10TB, 20GB, 100MB.| `maxQuota=2` - `quotaUnit` | Quota unit used by `maxQuota` parameter. Must be used with parameter `maxQuota`. Possible values: TB, GB, MB. | `quotaUnit=TB` - `maxUsers` | how many mail users this admin can create. It's shared by all domains created/managed by this admin. | `maxUsers=100` - `maxAliases` | how many mail aliases this admin can create. It's shared by all domains created/managed by this admin. | `maxAliases=200` - `maxLists` | how many mailing lists this admin can create. It's shared by all domains created/managed by this admin. | `maxLists=300` - -
- -!!! api "`DELETE`{: .delete } `/api/admin/`{: .url } `Delete an existing domain admin`{: .comment }" -!!! api "`PUT`{: .put } `/api/admin/`{: .url } `Update profile of an existing domain admin`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My Admin Name` - `password` | Password| `password=AsTr0ng@` - `accountStatus` | Enable or disable account. Possible values: `active`, `disabled`. | `accountStatus=active` - `language` | Preferred language of iRedAdmin web UI | `language=en_US` - `isGlobalAdmin` | Mark this admin as global admin | `isGlobalAdmin=yes` - - Below parameters are used by normal domain admin (`isGlobalAdmin=no`). With `isGlobalAdmin=yes`, these parameters will be discarded. - - Parameter | Summary | Sample Usage - --- |--- |--- - `maxDomains` | how many mail domains this admin can create | `maxDomains=5` - `maxQuota` | how much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter `quotaUnit`. Sample: 10TB, 20GB, 100MB.| `maxQuota=2` - `quotaUnit` | Quota unit used by `maxQuota` parameter. Must be used with parameter `maxQuota`. Possible values: TB, GB, MB. | `quotaUnit=TB` - `maxUsers` | how many mail users this admin can create. It's shared by all domains created/managed by this admin. | `maxUsers=100` - `maxAliases` | how many mail aliases this admin can create. It's shared by all domains created/managed by this admin. | `maxAliases=200` - `maxLists` | how many mailing lists this admin can create. It's shared by all domains created/managed by this admin. | `maxLists=300` - -
- -!!! api "`POST`{: .post } `/api/verify_password/admin/`{: .url } `Verify given (plain) password against the one stored in SQL/LDAP`{: .comment } `Parameters`{: .has_params} " - -
- - !!! attention - - Password verification is limited to global domain admin. - - Parameter | Summary | Sample Usage - --- |--- |--- - `password` | Plain password | `password=u0tBF82cIV@vi8Gme` - -
- -### Mail User {: .toggle } - -!!! api "`GET`{: .get } `/api/user/`{: .url } `Get profile of an existing mail user`{: .comment }" -!!! api "`POST`{: .post } `/api/user/`{: .url } `Create a new mail user`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My New Name` - `password` | Password| `password=AsTr0ng@` - `language` | Preferred language of iRedAdmin web UI | `language=en_US` - `quota` | Mailbox quota (in MB) | `quota=1024` - -
- -!!! api "`DELETE`{: .delete } `/api/user/`{: .url } `Delete an existing mail user`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/user//keep_mailbox_days/`{: .url } `Delete an existing mail user, and keep the mailbox for given days. Defaults to keep forever.`{: .comment }" -!!! api "`PUT`{: .put } `/api/user/`{: .url } `Update profile of an existing mail user`{: .comment } `Parameters`{: .has_params} " - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My New Name` - `password` | Password | `password=u0tBF82cIV@vi8Gme` - `quota` | Mailbox quota (in MB) | `quota=1024` - `accountStatus` | Enable or disable user. Possible values: `active`, `disabled`. | `accountStatus=active` - `language` | Preferred language of iRedAdmin web UI | `language=en_US` - `employeeid` | User ID (or Employee Number) | `employeeid=My Employee ID` - `transport` | Transport program | `transport=dovecot` - `isGlobalAdmin` | Promote user to be a global admin. Possible values: `yes`, `no` | `isGlobalAdmin=yes` - `forwarding` | Per-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses. | `forwarding=user1@domain.com,user2@domain.com,user3@domain.com` - `aliases` | Per-user alias addresses. Multiple addresses must be separated by comma. If empty, all per-user alias addresses owned by this user will be removed. Conflicts with parameter `addAlias` and `removeAlias`. | `aliases=user1@domain.com,user2@domain.com,user3@domain.com` - `addAlias` | Add new per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases`. | `addAlias=user1@domain.com,user2@domain.com,user3@domain.com` - `removeAlias` | Remove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases`. | `removeAlias=user1@domain.com,user2@domain.com,user3@domain.com` - `services` | Reset per-user enabled mail services to given values. Conflicts with parameter `addService` and `removeService`. See additional notes below. | `services=mail,smtp,pop3,imap` - `addService` | Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter `services`. See additional notes below. | `addService=vpn,owncloud` - `removeService` | Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter `services`. See additional notes below. | `removeService=forward,senderbcc` - - !!! attention - - Notes about `services`, `addService`, `removeService` parameters: - - * Available service names in iRedMail: - * smtp - * smtpsecured (SMTP over TLS or SSL) - * pop3 - * pop3secured (POP3 over TLS or SSL) - * imap - * imapsecured (IMAP over TLS or SSL) - * managesieve - * managesievesecured (Managesieve over TLS or SSL) - * deliver (deliver received email to local mailbox) - * sogo (SOGo groupware) - - * For LDAP backends, you're free to add custom service names, because - the LDAP attribute name used to store service names supports storing - multiple values and we don't need to change LDAP schema. - - * For SQL backends, column `enable` in SQL table - `vmail.mailbox` must be present, if not, specified service name will - be silently ignored. - -
- -!!! api "`POST`{: .put } `/api/user//change_email/`{: .url } `Change user's email address (from '' to '')`{: .comment }" -!!! api "`PUT`{: .put } `/api/users/`{: .url } `Update profiles of all users under domain`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Comment - --- |--- - `accountStatus` | Account status. Possible value is: active, disabled. - `password` | Password - `language` | Preferred language of iRedAdmin web UI - `transport` | Per-user transport - -
- -!!! api "`POST`{: .post } `/api/verify_password/user/`{: .url } `Verify given (plain) password against the one stored in SQL/LDAP`{: .comment } `Parameters`{: .has_params} " - -
- - !!! attention - - Password verification is limited to global domain admin. - - Parameter | Summary | Sample Usage - --- |--- |--- - `password` | Plain password | `password=u0tBF82cIV@vi8Gme` - -
- -### Mailing List {: .toggle } - -!!! attention - - Mailing list is only available in OpenLDAP backend. For SQL backends, - please use mail alias account as mailing list. - -!!! api "`GET`{: .get } `/api/maillist/`{: .url } `Get profile of an existing mailing list account`{: .comment }" -!!! api "`POST`{: .post } `/api/maillist/`{: .url } `Create a new mailing list`{: .comment } `Parameters`{: .has_params }" -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My List Name` - `accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public` - `members` | Members of mailing list. Multiple members must be separated by comma. | `members=user1@domain.com,user2@domain.com` - -
- -!!! api "`DELETE`{: .delete } `/api/maillist/`{: .url } `Delete an existing mailing list`{: .comment }" -!!! api "`PUT`{: .put } `/api/maillist/`{: .url } `Update profile of an existing mailing list`{: .comment } `Parameters`{: .has_params }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | display name | `name=My List Name` - `accessPolicy` | Defines who can send email to this mailing list | `accessPolicy=public` - `members` | Members of mailing list. Multiple members must be separated by comma. Conflict with parameter `addMember` and `removeMember`. | `members=user1@domain.com,user2@domain.com` - `addMember` | Add new members of mailing list. Multiple members must be separated by comma. Conflict with parameter `members`. | `addMember=user1@domain.com,user2@domain.com` - `removeMember` | Remove existing members of mailing list. Multiple members must be separated by comma. Conflict with parameter `members`. | `removeMember=user1@domain.com,user2@domain.com` - -
- -### Mail Alias {: .toggle } - -!!! api "`GET`{: .get } `/api/alias/`{: .url } `Get profile of an existing mail alias`{: .comment }" -!!! api "`POST`{: .post } `/api/alias/`{: .url } `Create a new mail alias`{: .comment } `Parameters`{: .has_params}" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My List Name` - `accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public` - `members` | Members of mail alias. Multiple members must be separated by comma. | `members=user1@domain.com,user2@domain.com` - - !!! attention - - `accessPolicy` for mail alias account is only available for SQL backends. - -
- -!!! api "`DELETE`{: .delete } `/api/alias/`{: .url } `Delete an existing mail alias`{: .comment }" -!!! api "`PUT`{: .put } `/api/alias/`{: .url } `Update profile of an existing mail alias`{: .comment } `Parameters`{: .has_params }" - -
- - !!! attention - - `accessPolicy` for mail alias account is only available for SQL backends. - - Parameter | Summary | Sample Usage - --- |--- |--- - `name` | Display name | `name=My List Name` - `accessPolicy` | Defines who can send email to this mail alias account | `accessPolicy=public` - `members` | Members of mail alias. Multiple members must be separated by comma. Conflict with parameter `addMember` and `removeMember`. | `members=user1@domain.com,user2@domain.com` - `addMember` | Add new members of mail alias. Multiple members must be separated by comma. Conflict with parameter `members`. | `addMember=user1@domain.com,user2@domain.com` - `removeMember` | Remove existing members of mail alias. Multiple members must be separated by comma. Conflict with parameter `members`. | `removeMember=user1@domain.com,user2@domain.com` - -
- -!!! api "`POST`{: .put } `/api/alias//change_email/`{: .url } `Change email address of alias account (from '' to '')`{: .comment }" - -### Spam Policy {: .toggle } - -!!! api "`GET`{: .get } `/api/spampolicy/global`{: .url } `Get global spam policy`{: .comment }" -!!! api "`GET`{: .get } `/api/spampolicy/domain/`{: .url } `Get per-domain spam policy`{: .comment }" -!!! api "`GET`{: .get } `/api/spampolicy/user/`{: .url } `Get per-user spam policy`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/spampolicy/global`{: .url } `Delete global spam policy`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/spampolicy/domain/`{: .url } `Delete per-domain spam policy`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/spampolicy/user/`{: .url } `Delete per-user spam policy`{: .comment }" -!!! api "`PUT`{: .put } `/api/spampolicy/global`{: .url } `Set global spam policy`{: .comment } `Parameters`{: .has_params_spampolicy }" -!!! api "`PUT`{: .put } `/api/spampolicy/domain/`{: .url } `Set per-domain spam policy`{: .comment } `Parameters`{: .has_params_spampolicy }" -!!! api "`PUT`{: .put } `/api/spampolicy/user/`{: .url } `Set per-user spam policy`{: .comment } `Parameters`{: .has_params_spampolicy }" - -
- - Parameters available for global, per-domain, per-user spam policies. - - > Per-user policy has the highest priority, then per-domain policy, then global policy. - - Parameter | Summary | Sample Usage - --- |--- |--- - `bypass_spam_checks` | Bypass spam checks | `bypass_spam_checks=yes` (default is `no`) - `bypass_virus_checks` | Bypass virus checks | `bypass_virus_checks=yes` (default is `no`) - `bypass_banned_checks` | Bypass banned file type checks | `bypass_banned_checks=yes` (default is `no`) - `bypass_header_checks` | Bypass bad header checks | `bypass_header_checks=yes` (default is `no`) - `quarantine_spam` | Quarantine detected spam into SQL database | `quarantine_spam=yes` (default is `no`) - `quarantine_virus` | Quarantine detected virus into SQL database | `quarantine_virus=no` (default is `yes`) - `quarantine_banned` | Quarantine email with banned file type into SQL database | `quarantine_banned=yes` (default is `no`) - `quarantine_bad_header` | Quarantine email with bad header into SQL database | `quarantine_bad_header=yes` (default is `no`) - `prefix_spam_in_subject` | Prefix string `[SPAM] ` in mail subject if it's spam | `prefix_spam_in_subject=yes` (default is `no`) - `always_insert_x_spam_headers` | Always insert `X-Spam-*` headers in email. It contains spam score and matched SpamAssassin rules. __Don't enable this unless you want to debug spam checking.__ | `always_insert_x_spam_headers=yes` (default is `no`) - `spam_score` | Set a preferred spam score, if scanned email has higher score than this one, it will be marked as spam. | `spam_score=4` (defaults to use system setting defined in Amavisd config file.) - -
- -### Throttling {: .toggle } - -!!! api "`GET`{: .get } `/api/throttle/global/inbound`{: .url } `Get global inbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle/global/inbound`{: .url } `Set global inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" -!!! api "`GET`{: .get } `/api/throttle/global/outbound`{: .url } `Get global outbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle/global/outbound`{: .url } `Set global inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" -!!! api "`GET`{: .get } `/api/throttle//inbound`{: .url } `Get domain inbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle//inbound`{: .url } `Set domain inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" -!!! api "`GET`{: .get } `/api/throttle//outbound`{: .url } `Get domain outbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle//outbound`{: .url } `Set domain outbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" -!!! api "`GET`{: .get } `/api/throttle//inbound`{: .url } `Get user inbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle//inbound`{: .url } `Set user inbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" -!!! api "`GET`{: .get } `/api/throttle//outbound`{: .url } `Get user outbound throttle settings`{: .comment }" -!!! api "`POST`{: .post } `/api/throttle//outbound`{: .url } `Set user outbound throttle settings`{: .comment } `Parameters`{: .has_params_throttle }" - -
- - Parameters available for global, per-domain, per-user throttle settings. - - Parameter | Summary | Sample Usage - --- |--- |--- - `period` * | Period of time, in seconds | `period=3600` (one hour) - `msg_size` | Max size of single email, in bytes | `msg_size=10485760` (10 MB) - `max_msgs` | Number of max inbound emails | `max_msgs=20` (up to 20 messages) - `max_quota` | Cumulative size of inbound or outbound emails, in bytes | `max_quota=1048576000` (1 GB) - -
- -### Greylisting {: .toggle } - -!!! api "`GET`{: .get } `/api/greylisting/all`{: .url } `Get all existing greylisting settings`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting/global`{: .url } `Get global greylisting setting`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting/`{: .url } `Get per-domain greylisting setting`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting/`{: .url } `Get per-user greylisting setting`{: .comment }" -!!! api "`POST`{: .post } `/api/greylisting/global`{: .url } `Set global greylisting setting`{: .comment } `Parameters`{: .has_params_greylisting }" -!!! api "`POST`{: .post } `/api/greylisting/`{: .url } `Set per-domain greylisting setting`{: .comment } `Parameters`{: .has_params_greylisting }" -!!! api "`POST`{: .post } `/api/greylisting/`{: .url } `Set per-user greylisting setting`{: .comment } `Parameters`{: .has_params_greylisting }" - -
- - Parameters available for global, per-domain and per-user greylisting settings. - - Parameter | Summary | Sample Usage - --- |--- |--- - `status` | Explicitly enable or disable greylisting service. | `status=enable` (or `disable`) - -
- -!!! api "`DELETE`{: .delete } `/api/greylisting/global`{: .url } `Delete global greylisting setting`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/greylisting/`{: .url } `Delete per-domain greylisting setting`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/greylisting/`{: .url } `Delete per-user greylisting setting`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting/global/whitelists`{: .url } `Get globally whitelisted senders for greylisting service`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting//whitelists`{: .url } `Get whitelisted senders for greylisting service for specified domain`{: .comment }" -!!! api "`GET`{: .get } `/api/greylisting//whitelists`{: .url } `Get whitelisted senders for greylisting service for specified user`{: .comment }" -!!! api "`POST`{: .post } `/api/greylisting/global/whitelists`{: .url } `Whitelist senders for greylisting service globally`{: .comment } `Parameters`{: .has_params_greylisting_whitelists }" -!!! api "`POST`{: .post } `/api/greylisting//whitelists`{: .url } `Whitelist senders for greylisting service for specified domain`{: .comment } `Parameters`{: .has_params_greylisting_whitelists }" -!!! api "`POST`{: .post } `/api/greylisting//whitelists`{: .url } `Whitelist senders for greylisting services for specified user`{: .comment } `Parameters`{: .has_params_greylisting_whitelists }" - -
- - Parameter | Summary | Sample Usage - --- |--- |--- - `senders` | Reset whitelisted senders for global greylisting service to given senders. Multiple addresses must be separated by comma. Conflicts with parameter `addSenders` and `removeSenders`. | `senders=192.168.1.0/24,172.16.10.1,@example.com` - `addSenders` | Whitelist new senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter `senders`. | `addSenders=192.168.1.0/24,@example.com` - `removeSenders` | Remove existing whitelisted senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter `senders`. | `removeSenders=192.168.1.0/24,@example.com` - - Valid sender address formats: - - Sender Address | Comment - ---|--- - `192.168.2.10` | Single IP address - `192.168.1.0/24` | CIDR network - `user@example.com` | Single email address - `@example.com` | Entire domain - `@.example.com` | Entire domain and all its sub-domains - -
- -!!! api "`POST`{: .post } `/api/greylisting/whitelist_spf_domains`{: .url } `Whitelist IP addresses and networks listed in SPF/MX DNS record of given sender domains for greylisting service globally`{: .comment } `Parameters`{: .has_params }" - -
- - Given sender domain names are not used directly while checking whitelisting, instead, there's a cron job to query SPF and MX DNS records of given sender domains, then whitelist the IP addresses/networks listed in DNS records. - - Multiple domains must be separated by comma. - - Parameter | Summary | Sample Usage - --- |--- |--- - `domains` | Reset whitelisted sender domains for global greylisting service to given sender domains. Conflicts with parameters `addDomains` and `removeDomains`. | `domains=iredmail.org,gmail.com` - `addDomains` | Add new whitelist sender domains for global greylisting service. Conflicts with parameter `domains`. | `addDomains=iredmail.org,gmail.com` - `removeDomains` | Remove existing whitelisted sender domains for global greylisting service. Conflicts with parameter `domains`. | `removeDomains=iredmail.org,gmail.com` - - - -
- -### Export Accounts {: .toggle } - -#### LDIF (LDAP backend only) {: .toggle } - -!!! api "`GET`{: .get } `/api/ldif/domain/`{: .url } `Export domain to LDIF`{: .comment }" -!!! api "`GET`{: .get } `/api/ldif/catchall/`{: .url } `Export per-domain catch-all account to LDIF`{: .comment }" -!!! api "`GET`{: .get } `/api/ldif/admin/`{: .url } `Export (separated) domain admin to LDIF`{: .comment }" -!!! api "`GET`{: .get } `/api/ldif/user/`{: .url } `Export mail user to LDIF`{: .comment }" -!!! api "`GET`{: .get } `/api/ldif/maillist/`{: .url } `Export mailing list account to LDIF`{: .comment }" -!!! api "`GET`{: .get } `/api/ldif/alias/`{: .url } `Export mail alias account to LDIF`{: .comment }" - - - - - -## ChangeLog - -### iRedAdmin-Pro-SQL-2.8.0, iRedAdmin-Pro-LDAP-3.0 - -+ NEW: Able to list all managed domains (/domains). -+ NEW: Able to manage per-usre enabled mail services (/user/). -+ NEW: Able to promote mail user to be a global admin (/user/). -+ Enhancement: Return managed domain names while getting user (must - have admin privilege) or admin profile. - -* Fixed issues: - * It always requires password while updating domain admin profile. - -* iRedAdmin-Pro-LDAP-3.0: - * LDAP attribute 'accountSetting' is now converted to a Python dictionary in returned JSON. - - * Old value: `{'accountSetting': ['create_new_domains:yes', 'create_max_domains:5', ...], ...}` - * New value: `{'accountSetting': {'create_new_domains': 'yes', 'create_max_domains': 5, ...}}` - -### iRedAdmin-Pro-SQL-2.7.0, iRedAdmin-Pro-LDAP-2.9.0 - -* New: Able to manage global, per-domain and per-user greylisting settings, - whitelist senders, and global whitelisted SPF domains. -* iRedAdmin-Pro-SQL-2.7.0: - * Variable names changed in returned JSON data of user profile (`GET /api/user/`): - * name `forwarding` is replaced by `forwardings`, and it's now a list - object of user forwarding email addresses (was a string, multiple - addresses were separated by comma). - * Variable names in returned JSON data of mail alias profile (`GET /api/alias/`): - * name `islist` is gone. - * name `goto` is replaced by `members`, and it's now a list object of - member email addresses (was a string, multiple addresses were separated - by comma). - * Variable names in returned JSON data of domain profile (`GET /api/domain/`): - * name `catchall` always presents, and it's now a list object of catch-all - email address (was a string, multiple addresses were separated by comma). - * Fixed bugs: - * Cannot set per-user alias addresses while creating new mail user. - * Cannot add or remove per-user alias addresses while updating user profile. - * User mailbox quota was removed while updating user profile. - * Not use default transport setting while creating new domain. - -### iRedAdmin-Pro-SQL-2.6.0, iRedAdmin-Pro-LDAP-2.8.0 - -* Variable names in returned JSON data has been changed to: - `{'_success': ..., '_msg': ...}` (was `{'success': ..., 'msg': ...}`). -* Some variable names have been renamed: - * `cn` -> `name`. - * `mailQuota` -> `quota` - * `preferredLanguage` -> `language` - - - - - - diff --git a/en_US/iredadmin/2-iredadmin-pro.restful.api.md b/en_US/iredadmin/2-iredadmin-pro.restful.api.md index c36020b8..9ea9c06f 100644 --- a/en_US/iredadmin/2-iredadmin-pro.restful.api.md +++ b/en_US/iredadmin/2-iredadmin-pro.restful.api.md @@ -4,8 +4,8 @@ !!! attention - * This document is applicable to `iRedAdmin-Pro-SQL-2.7.0` and - `iRedAdmin-Pro-LDAP-2.9.0`. If you're running an old release, please + * This document is applicable to `iRedAdmin-Pro-SQL-2.8.0` and + `iRedAdmin-Pro-LDAP-3.0`. If you're running an old release, please upgrade iRedAdmin-Pro to the latest release, or check [document for old releases](./iredadmin-pro.releases.html). * If you need an API which has not yet been implemented, don't hesitate to @@ -81,6 +81,17 @@ Notes: ### Domain {: .toggle } +!!! api "`GET`{: .get } `/api/domains`{: .url } `Get profiles of all managed mail domains`{: .comment } `Parameters`{: .has_params }" + +
+ + Parameter | Summary | Sample Usage + --- |--- |--- + `name_only` | Return only mail domain names | `name_only=yes` + `disabled_only` | Return only disabled mail domains | `disabled_only=yes` + +
+ !!! api "`GET`{: .get } `/api/domain/`{: .url } `Get profile of an existing domain`{: .comment }" !!! api "`POST`{: .post } `/api/domain/`{: .url } `Create a new domain`{: .comment } `Parameters`{: .has_params }" @@ -88,7 +99,7 @@ Notes: Parameter | Summary | Sample Usage --- |--- |--- - `name` | Short description of this domain name. e.g. company name | `name=Google Inc` + `name`* | Short description of this domain name. e.g. company name | `name=Google Inc` `quota` | Per-domain mailbox quota, in MB. | `quota=2048` `language` | Default preferred language for newly created mail user | `language=en_US` `transport` | Transport program | `transport=dovecot` @@ -103,7 +114,7 @@ Notes: !!! api "`DELETE`{: .delete } `/api/domain/`{: .url } `Delete an existing domain (all mail messages will NOT be removed)`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/domain//keep_mailbox_days/`{: .url } `Delete domain, and keep all mail messages for given days`{: .comment }" +!!! api "`DELETE`{: .delete } `/api/domain//keep_mailbox_days/`{: .url } `Delete domain, and keep all mail messages for given days. Defaults to keep forever.`{: .comment }" !!! api "`PUT`{: .put } `/api/domain/`{: .url } `Update profile of an existing domain`{: .comment } `Parameters`{: .has_params }"
@@ -295,7 +306,7 @@ Notes:
!!! api "`DELETE`{: .delete } `/api/user/`{: .url } `Delete an existing mail user`{: .comment }" -!!! api "`DELETE`{: .delete } `/api/user//keep_mailbox_days/`{: .url } `Delete an existing mail user, and keep the mailbox for given days. Defaults to 100 years.`{: .comment }" +!!! api "`DELETE`{: .delete } `/api/user//keep_mailbox_days/`{: .url } `Delete an existing mail user, and keep the mailbox for given days. Defaults to keep forever.`{: .comment }" !!! api "`PUT`{: .put } `/api/user/`{: .url } `Update profile of an existing mail user`{: .comment } `Parameters`{: .has_params} "
@@ -309,10 +320,38 @@ Notes: `language` | Preferred language of iRedAdmin web UI | `language=en_US` `employeeid` | User ID (or Employee Number) | `employeeid=My Employee ID` `transport` | Transport program | `transport=dovecot` + `isGlobalAdmin` | Promote user to be a global admin. Possible values: `yes`, `no` | `isGlobalAdmin=yes` `forwarding` | Per-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses. | `forwarding=user1@domain.com,user2@domain.com,user3@domain.com` `aliases` | Per-user alias addresses. Multiple addresses must be separated by comma. If empty, all per-user alias addresses owned by this user will be removed. Conflicts with parameter `addAlias` and `removeAlias`. | `aliases=user1@domain.com,user2@domain.com,user3@domain.com` `addAlias` | Add new per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases`. | `addAlias=user1@domain.com,user2@domain.com,user3@domain.com` `removeAlias` | Remove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter `aliases`. | `removeAlias=user1@domain.com,user2@domain.com,user3@domain.com` + `services` | Reset per-user enabled mail services to given values. Conflicts with parameter `addService` and `removeService`. See additional notes below. | `services=mail,smtp,pop3,imap` + `addService` | Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter `services`. See additional notes below. | `addService=vpn,owncloud` + `removeService` | Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter `services`. See additional notes below. | `removeService=forward,senderbcc` + + !!! attention + + Notes about `services`, `addService`, `removeService` parameters: + + * Available service names in iRedMail: + * smtp + * smtpsecured (SMTP over TLS or SSL) + * pop3 + * pop3secured (POP3 over TLS or SSL) + * imap + * imapsecured (IMAP over TLS or SSL) + * managesieve + * managesievesecured (Managesieve over TLS or SSL) + * deliver (deliver received email to local mailbox) + * sogo (SOGo groupware) + + * For LDAP backends, you're free to add custom service names, because + the LDAP attribute name used to store service names supports storing + multiple values and we don't need to change LDAP schema. + + * For SQL backends, column `enable` in SQL table + `vmail.mailbox` must be present, if not, specified service name will + be silently ignored.
@@ -567,6 +606,25 @@ Notes: ## ChangeLog +### iRedAdmin-Pro-SQL-2.8.0, iRedAdmin-Pro-LDAP-3.0 + +* NEW: Able to list all managed domains (`/domains`). +* NEW: Able to manage per-usre enabled mail services (`/user/`). +* NEW: Able to promote mail user to be a global admin (`/user/`). +* Enhancement: Return managed domain names while getting user (must + have admin privilege) or admin profile. + +* Fixed issues: + * It always requires password while updating domain admin profile. + +* iRedAdmin-Pro-LDAP-3.0: + * Enhancement: Return per-domain catchall addresses in domain profile. + * LDAP attribute 'accountSetting' is now converted to a dictionary + in returned JSON. + + * Old value: `{'accountSetting': ['create_new_domains:yes', 'create_max_domains:5', ...], ...}` + * New value: `{'accountSetting': {'create_new_domains': 'yes', 'create_max_domains': 5, ...}}` + ### iRedAdmin-Pro-SQL-2.7.0, iRedAdmin-Pro-LDAP-2.9.0 * New: Able to manage global, per-domain and per-user greylisting settings, diff --git a/html/iredadmin-pro.restful.api.html b/html/iredadmin-pro.restful.api.html index aea3e242..b78a5361 100644 --- a/html/iredadmin-pro.restful.api.html +++ b/html/iredadmin-pro.restful.api.html @@ -39,6 +39,7 @@
  • ChangeLog @@ -50,8 +51,8 @@

    Attention

      -
    • This document is applicable to iRedAdmin-Pro-SQL-2.7.0 and - iRedAdmin-Pro-LDAP-2.9.0. If you're running an old release, please +
    • This document is applicable to iRedAdmin-Pro-SQL-2.8.0 and + iRedAdmin-Pro-LDAP-3.0. If you're running an old release, please upgrade iRedAdmin-Pro to the latest release, or check document for old releases.
    • If you need an API which has not yet been implemented, don't hesitate to @@ -139,6 +140,34 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]

    Domain

    +

    GET /api/domains Get profiles of all managed mail domains Parameters

    +
    + + + + + + + + + + + + + + + + + + + + + +
    ParameterSummarySample Usage
    name_onlyReturn only mail domain namesname_only=yes
    disabled_onlyReturn only disabled mail domainsdisabled_only=yes
    +
    + +
    +

    GET /api/domain/<domain> Get profile of an existing domain

    @@ -155,7 +184,7 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...] -name +name* Short description of this domain name. e.g. company name name=Google Inc @@ -218,7 +247,7 @@ RESTFUL_API_CLIENTS = ['172.16.244.1', ...]

    DELETE /api/domain/<domain> Delete an existing domain (all mail messages will NOT be removed)

    -

    DELETE /api/domain/<domain>/keep_mailbox_days/<number> Delete domain, and keep all mail messages for given days

    +

    DELETE /api/domain/<domain>/keep_mailbox_days/<number> Delete domain, and keep all mail messages for given days. Defaults to keep forever.

    PUT /api/domain/<domain> Update profile of an existing domain Parameters

    @@ -823,7 +852,7 @@ to be a domain admin.

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

    -

    DELETE /api/user/<mail>/keep_mailbox_days/<number> Delete an existing mail user, and keep the mailbox for given days. Defaults to 100 years.

    +

    DELETE /api/user/<mail>/keep_mailbox_days/<number> Delete an existing mail user, and keep the mailbox for given days. Defaults to keep forever.

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

    @@ -874,6 +903,11 @@ to be a domain admin.

    transport=dovecot +isGlobalAdmin +Promote user to be a global admin. Possible values: yes, no +isGlobalAdmin=yes + + forwarding Per-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses. forwarding=user1@domain.com,user2@domain.com,user3@domain.com @@ -893,8 +927,54 @@ to be a domain admin.

    Remove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter aliases. removeAlias=user1@domain.com,user2@domain.com,user3@domain.com + +services +Reset per-user enabled mail services to given values. Conflicts with parameter addService and removeService. See additional notes below. +services=mail,smtp,pop3,imap + + +addService +Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter services. See additional notes below. +addService=vpn,owncloud + + +removeService +Add new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter services. See additional notes below. +removeService=forward,senderbcc + +
    +

    Attention

    +

    Notes about services, addService, removeService parameters:

    +
      +
    • +

      Available service names in iRedMail:

      +
        +
      • smtp
        • +
      • smtpsecured (SMTP over TLS or SSL)
        • +
      • pop3
        • +
      • pop3secured (POP3 over TLS or SSL)
        • +
      • imap
        • +
      • imapsecured (IMAP over TLS or SSL)
        • +
      • managesieve
        • +
      • managesievesecured (Managesieve over TLS or SSL)
        • +
      • deliver (deliver received email to local mailbox)
        • +
      • sogo (SOGo groupware)
        • +
      +
      • +
    • +

      For LDAP backends, you're free to add custom service names, because + the LDAP attribute name used to store service names supports storing + multiple values and we don't need to change LDAP schema.

      +
      • +
    • +

      For SQL backends, column enable<service> in SQL table + vmail.mailbox must be present, if not, specified service name will + be silently ignored.

      +
      • +
    +
    @@ -1509,6 +1589,36 @@ please use mail alias account as mailing list.

    GET /api/ldif/alias/<mail> Export mail alias account to LDIF

    ChangeLog

    +

    iRedAdmin-Pro-SQL-2.8.0, iRedAdmin-Pro-LDAP-3.0

    +
      +
    • NEW: Able to list all managed domains (/domains).
      • +
    • NEW: Able to manage per-usre enabled mail services (/user/<mail>).
      • +
    • NEW: Able to promote mail user to be a global admin (/user/<mail>).
      • +
    • +

      Enhancement: Return managed domain names while getting user (must + have admin privilege) or admin profile.

      +
      • +
    • +

      Fixed issues:

      +
        +
      • It always requires password while updating domain admin profile.
        • +
      +
      • +
    • +

      iRedAdmin-Pro-LDAP-3.0:

      +
        +
      • Enhancement: Return per-domain catchall addresses in domain profile.
        • +
      • +

        LDAP attribute 'accountSetting' is now converted to a dictionary + in returned JSON.

        +
          +
        • Old value: {'accountSetting': ['create_new_domains:yes', 'create_max_domains:5', ...], ...}
          • +
        • New value: {'accountSetting': {'create_new_domains': 'yes', 'create_max_domains': 5, ...}}
          • +
        +
        • +
      +
      • +

    iRedAdmin-Pro-SQL-2.7.0, iRedAdmin-Pro-LDAP-2.9.0

    • New: Able to manage global, per-domain and per-user greylisting settings, diff --git a/html/iredadmin-pro.restful.api.new.html b/html/iredadmin-pro.restful.api.new.html deleted file mode 100644 index f5d9378a..00000000 --- a/html/iredadmin-pro.restful.api.new.html +++ /dev/null @@ -1,1702 +0,0 @@ - - - - - iRedAdmin-Pro: RESTful API - - - - -

      iRedAdmin-Pro: RESTful API

      -
      - -
      -
      -

      Attention

      -
        -
      • This document is applicable to iRedAdmin-Pro-SQL-2.8.0 and - iRedAdmin-Pro-LDAP-3.0. If you're running an old release, please - upgrade iRedAdmin-Pro to the latest release, or check - document for old releases.
        • -
      • If you need an API which has not yet been implemented, don't hesitate to - contact us.
        • -
      -
      -

      Summary

      -

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

      -
        -
      • If operation succeed:
          -
        • For http POST, DELETE, PUT methods, it returns JSON data: {'_success': true}.
          • -
        • For http GET method, it returns JSON data: {'_success': true, '_data': <program_output>}.
          • -
        -
        • -
      • If operation failed, it returns JSON data: {'_success': false, '_msg': '<error_reason>'}.
        • -
      -

      Enable RESTful API

      -

      RESTful API is disabled by default, to enable it, please add setting below in -iRedAdmin-Pro config file settings.py:

      -
      ENABLE_RESTFUL_API = True
-
      - -

      Restarting Apache or uwsgi (if you're running Nginx) is required after changed -iRedAdmin config file.

      -
      -

      iRedAdmin-Pro config file location

      -
        -
      • on RHEL/CentOS, it's /var/www/iredadmin/settings.py.
        • -
      • on Debian/Ubuntu, it's /opt/www/iredadmin/settings.py (in recent iRedMail releases) or /usr/share/apache2/iredadmin/settings.py (in old iRedMail releases).
        • -
      • on FreeBSD, it's /usr/local/www/iredadmin/settings.py.
        • -
      • on OpenBSD, it's /var/www/iredadmin/settings.py.
        • -
      -
      -

      To restrict API access to few IP addresses, please also add settings below in -iRedAdmin-Pro config file:

      -
      # Enable restriction
-RESTRICT_API_ACCESS = True
-
-# List all IP addresses of allowed client for API access.
-RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
-
      - -

      Sample code to interact with iRedAdmin-Pro RESTful API

      - -

      APIs

      -

      Notes:

      -
        -
      • Parameter name with a * mark means the parameter is required, otherwise is optional.
        • -
      • replace <domain> in URL by the real domain name. e.g. example.com
        • -
      • replace <mail> in URL by the real email address. e.g. user@domain.com
        • -
      • replace <number> in URL by an integer number. e.g. 30, 200
        • -
      -

      -

      Login

      -
      -

      POST /api/login Login with an admin username (full email address) and password Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      usernameAdmin username. Must be a full email address.username=admin@mydomain.com
      password(Plain) admin password.password=AsTr0ng@
      -
      - -
      -

      Domain

      -
      -

      GET /api/domains Get profiles of all managed mail domains Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      name_onlyReturn only mail domain namesname_only=yes
      disabled_onlyReturn only disabled mail domainsdisabled_only=yes
      -
      - -
      -
      -

      GET /api/domain/<domain> Get profile of an existing domain

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      name*Short description of this domain name. e.g. company namename=Google Inc
      quotaPer-domain mailbox quota, in MB.quota=2048
      languageDefault preferred language for newly created mail userlanguage=en_US
      transportTransport programtransport=dovecot
      defaultQuotaDefault per-user mailbox quota for newly created user, in MB.defaultQuota=1024
      maxUserQuotaMax mailbox quota of a mail user, in MB.maxUserQuota=2048
      numberOfUsersMax number of mail user accountsnumberOfUsers=20
      numberOfAliasesMax number of mail alias accountsnumberOfAliases=30
      numberOfListsMax number of mailing list accounts (Available in LDAP backends)numberOfLists=40
      senderBccPer-domain sender bccsenderBcc=user@domain.com
      recipientBccPer-domain recipient bccrecipientBcc=user@domain.com
      -
      - -
      -
      -

      DELETE /api/domain/<domain> Delete an existing domain (all mail messages will NOT be removed)

      -
      -
      -

      DELETE /api/domain/<domain>/keep_mailbox_days/<number> Delete domain, and keep all mail messages for given days. Defaults to keep forever.

      -
      -
      -

      PUT /api/domain/<domain> Update profile of an existing domain Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameShort description of this domain name. e.g. company namename=Google Inc
      accountStatusEnable or disable domain. Possible values: active, disabled.accountStatus=active
      quotaMailbox quota for whole domain, in MB.quota=2048
      languageDefault preferred language for newly created mail userlanguage=en_US
      transportTransport programtransport=dovecot
      minPasswordLengthMinimal password lengthminPasswordLength=8
      maxPasswordLengthMaximum password lengthminPasswordLength=20
      defaultQuotaDefault per-user mailbox quota for newly created userdefaultQuota=1024
      maxUserQuotaMax mailbox quota of a mail usermaxUserQuota=2048
      numberOfUsersMax number of mail user accountsnumberOfUsers=20
      numberOfAliasesMax number of mail alias accountsnumberOfAliases=30
      senderBccPer-domain sender bcc addresssenderBcc=user@domain.com
      recipientBccPer-domain recipient bcc addressrecipientBcc=user@domain.com
      is_backupmxMark domain as Backup MX. Must be used with parameter primarymx. Conflicts with parameter transport.is_backupmx=yes (or no)
      primarymxHostname or IP address of primary MX, smtp port number is optional. Must be used with parameter is_backupmx. Conflicts with parameter transport.primarymx=202.96.134.133, primarymx=[mail.iredmail.org]:25
      catchallPer-domain catch-all account (a list of email addresses used to receive emails sent to non-existing addresses under same domain). Multiple addresses must be separated by comma. Set an empty value to disable catch-all support.catchall=user@domain.com,user2@domain.com or catchall= (disable catch-all)
      outboundRelayPer-domain outbound relay. Set an empty value to disable outbound relay.outboundRelay=smtp:[192.168.1.2]:25 or outboundRelay= (disable outbound relay)
      enableServiceEnable new services. Multiple services must be separated by comma. Available services are listed below.enableService=self-service
      disableServiceDisable existing services. Multiple services must be separated by comma. Available services are listed below.disableService=self-service
      removeAllServicesDisable all services (including mail service)removeAllServices= (empty value)
      disableDomainProfiledisable given domain profiles. Normal admin cannot view and update disabled profiles in domain profile page. Available domain profiles are listed below.disableDomainProfile=bcc,relay,aliases
      enableDomainProfileenable given domain profiles. Normal admin can view and update disabled profiles in domain profile page. Available domain profiles are listed below.enableDomainProfile=bcc,relay,aliases
      disableUserProfiledisable given user profiles. Normal admin cannot view and update disabled profiles in user profile page. Available user profiles are listed below.disableUserProfile=bcc,relay,aliases
      enableUserProfileenable given domain profiles. Normal admin can view and update disabled profiles in user profile page. Available user profiles are listed below.enableUserProfile=bcc,relay,aliases
      disableUserPreferencedisable given user preferences in self-service page. Normal mail user cannot view and update disabled preferences. Available user preferences are listed below.disableUserPreference=forwarding,wblist
      enableUserPreferencedisable given user preferences in self-service page. Normal mail user can view and update disabled preferences. Available user preferences are listed below.enableUserProfile=forwarding,wblist
      -

      Available mail services:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      self-serviceEnable self-service for the mail domain.
      mailAll mail services. (LDAP backends only)
      domainaliasAlias domain support. (LDAP backends only)
      senderbccPer-domain sender bcc. (LDAP backends only)
      recipientbccPer-domain recipient bcc. (LDAP backends only)
      -

      Available domain profiles:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      bccPer-domain sender bcc and recipient bcc
      relayPer-domain inbound relay and outbound relay
      catchallPer-domain catchall account
      aliasesAlias domains
      throttlePer-domain inbound and outbound throttling
      greylistingPer-domain greylisting service
      wblistPer-domain whitelists and blacklists
      spampolicyPer-domain spam policy
      backupmxBackup MX
      advancedSome extra settings
      -

      Available user profiles:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      bccPer-user sender bcc and recipient bcc
      forwardingPer-user mail forwarding addresses
      relayPer-user inbound relay and outbound relay
      aliasesPer-user alias addresses
      throttlePer-user inbound and outbound throttling
      greylistingPer-user greylisting service
      wblistPer-user whitelists and blacklists
      spampolicyPer-user spam policy
      -

      Available user preferences (self-service):

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      personal_infoName, time zone, preferred language of web UI
      forwardingPer-user mail forwarding addresses
      wblistPer-user whitelists and blacklists
      quarantineManage quarantined mails
      rcvd_mailsView basic info of received mails, and whitelist/blacklist mail sender directly.
      spampolicyPer-user spam policy
      -
      - -
      -
      -

      PUT /api/domain/admins/<domain> Manage normal domain admins. Parameters

      -
      - -
      -

      Attention

      -

      Normal domain admin can only promote mail users under managed domains -to be a domain admin.

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      addAdminAdd new domain admins. Multiple services must be separated by comma.addAdmin=one@domain.com,two@domain.com
      removeAdminRemove existing domain admins. Multiple services must be separated by comma.removeAdmin=one@domain.com,two@domain.com
      removeAllAdminsRemove all existing domain admins.removeAllAdmins= (empty value)
      -
      - -
      -

      Domain Admin

      -
      -

      Attention

      -
        -
      • This is standalone domain admin account, not mail user with admin privileges.
        • -
      • Only global admin can access these APIs.
        • -
      -
      -
      -

      GET /api/admin/<mail> Get profile of an existing domain admin

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My Admin Name
      passwordPasswordpassword=AsTr0ng@
      accountStatusEnable or disable account. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      isGlobalAdminMark this admin as global adminisGlobalAdmin=yes
      -

      Below parameters are used by normal domain admin (isGlobalAdmin=no). With isGlobalAdmin=yes, these parameters will be discarded.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      maxDomainshow many mail domains this admin can createmaxDomains=5
      maxQuotahow much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter quotaUnit. Sample: 10TB, 20GB, 100MB.maxQuota=2
      quotaUnitQuota unit used by maxQuota parameter. Must be used with parameter maxQuota. Possible values: TB, GB, MB.quotaUnit=TB
      maxUsershow many mail users this admin can create. It's shared by all domains created/managed by this admin.maxUsers=100
      maxAliaseshow many mail aliases this admin can create. It's shared by all domains created/managed by this admin.maxAliases=200
      maxListshow many mailing lists this admin can create. It's shared by all domains created/managed by this admin.maxLists=300
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My Admin Name
      passwordPasswordpassword=AsTr0ng@
      accountStatusEnable or disable account. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      isGlobalAdminMark this admin as global adminisGlobalAdmin=yes
      -

      Below parameters are used by normal domain admin (isGlobalAdmin=no). With isGlobalAdmin=yes, these parameters will be discarded.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      maxDomainshow many mail domains this admin can createmaxDomains=5
      maxQuotahow much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter quotaUnit. Sample: 10TB, 20GB, 100MB.maxQuota=2
      quotaUnitQuota unit used by maxQuota parameter. Must be used with parameter maxQuota. Possible values: TB, GB, MB.quotaUnit=TB
      maxUsershow many mail users this admin can create. It's shared by all domains created/managed by this admin.maxUsers=100
      maxAliaseshow many mail aliases this admin can create. It's shared by all domains created/managed by this admin.maxAliases=200
      maxListshow many mailing lists this admin can create. It's shared by all domains created/managed by this admin.maxLists=300
      -
      - -
      -
      -

      POST /api/verify_password/admin/<mail> Verify given (plain) password against the one stored in SQL/LDAP Parameters

      -
      - -
      -

      Attention

      -

      Password verification is limited to global domain admin.

      -
      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      passwordPlain passwordpassword=u0tBF82cIV@vi8Gme
      -
      - -
      -

      Mail User

      -
      -

      GET /api/user/<mail> Get profile of an existing mail user

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My New Name
      passwordPasswordpassword=AsTr0ng@
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      quotaMailbox quota (in MB)quota=1024
      -
      - -
      -
      -

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

      -
      -
      -

      DELETE /api/user/<mail>/keep_mailbox_days/<number> Delete an existing mail user, and keep the mailbox for given days. Defaults to keep forever.

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My New Name
      passwordPasswordpassword=u0tBF82cIV@vi8Gme
      quotaMailbox quota (in MB)quota=1024
      accountStatusEnable or disable user. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      employeeidUser ID (or Employee Number)employeeid=My Employee ID
      transportTransport programtransport=dovecot
      isGlobalAdminPromote user to be a global admin. Possible values: yes, noisGlobalAdmin=yes
      forwardingPer-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses.forwarding=user1@domain.com,user2@domain.com,user3@domain.com
      aliasesPer-user alias addresses. Multiple addresses must be separated by comma. If empty, all per-user alias addresses owned by this user will be removed. Conflicts with parameter addAlias and removeAlias.aliases=user1@domain.com,user2@domain.com,user3@domain.com
      addAliasAdd new per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter aliases.addAlias=user1@domain.com,user2@domain.com,user3@domain.com
      removeAliasRemove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter aliases.removeAlias=user1@domain.com,user2@domain.com,user3@domain.com
      servicesReset per-user enabled mail services to given values. Conflicts with parameter addService and removeService. See additional notes below.services=mail,smtp,pop3,imap
      addServiceAdd new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter services. See additional notes below.addService=vpn,owncloud
      removeServiceAdd new per-user enabled mail service(s). Multiple values must be separated by comma. Conflicts with parameter services. See additional notes below.removeService=forward,senderbcc
      -
      -

      Attention

      -

      Notes about services, addService, removeService parameters:

      -
        -
      • -

        Available service names in iRedMail:

        -
          -
        • smtp
          • -
        • smtpsecured (SMTP over TLS or SSL)
          • -
        • pop3
          • -
        • pop3secured (POP3 over TLS or SSL)
          • -
        • imap
          • -
        • imapsecured (IMAP over TLS or SSL)
          • -
        • managesieve
          • -
        • managesievesecured (Managesieve over TLS or SSL)
          • -
        • deliver (deliver received email to local mailbox)
          • -
        • sogo (SOGo groupware)
          • -
        -
        • -
      • -

        For LDAP backends, you're free to add custom service names, because - the LDAP attribute name used to store service names supports storing - multiple values and we don't need to change LDAP schema.

        -
        • -
      • -

        For SQL backends, column enable<service> in SQL table - vmail.mailbox must be present, if not, specified service name will - be silently ignored.

        -
        • -
      -
      -
      - -
      -
      -

      POST /api/user/<mail>/change_email/<new_mail> Change user's email address (from '<mail>' to '<new_mail>')

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterComment
      accountStatusAccount status. Possible value is: active, disabled.
      passwordPassword
      languagePreferred language of iRedAdmin web UI
      transportPer-user transport
      -
      - -
      -
      -

      POST /api/verify_password/user/<mail> Verify given (plain) password against the one stored in SQL/LDAP Parameters

      -
      - -
      -

      Attention

      -

      Password verification is limited to global domain admin.

      -
      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      passwordPlain passwordpassword=u0tBF82cIV@vi8Gme
      -
      - -
      -

      Mailing List

      -
      -

      Attention

      -

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

      -
      -
      -

      GET /api/maillist/<mail> Get profile of an existing mailing list account

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mailing list. Multiple members must be separated by comma.members=user1@domain.com,user2@domain.com
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      namedisplay namename=My List Name
      accessPolicyDefines who can send email to this mailing listaccessPolicy=public
      membersMembers of mailing list. Multiple members must be separated by comma. Conflict with parameter addMember and removeMember.members=user1@domain.com,user2@domain.com
      addMemberAdd new members of mailing list. Multiple members must be separated by comma. Conflict with parameter members.addMember=user1@domain.com,user2@domain.com
      removeMemberRemove existing members of mailing list. Multiple members must be separated by comma. Conflict with parameter members.removeMember=user1@domain.com,user2@domain.com
      -
      - -
      -

      Mail Alias

      -
      -

      GET /api/alias/<mail> Get profile of an existing mail alias

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mail alias. Multiple members must be separated by comma.members=user1@domain.com,user2@domain.com
      -
      -

      Attention

      -

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

      -
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - -
      -

      Attention

      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mail alias. Multiple members must be separated by comma. Conflict with parameter addMember and removeMember.members=user1@domain.com,user2@domain.com
      addMemberAdd new members of mail alias. Multiple members must be separated by comma. Conflict with parameter members.addMember=user1@domain.com,user2@domain.com
      removeMemberRemove existing members of mail alias. Multiple members must be separated by comma. Conflict with parameter members.removeMember=user1@domain.com,user2@domain.com
      -
      - -
      -
      -

      POST /api/alias/<mail>/change_email/<new_mail> Change email address of alias account (from '<mail>' to '<new_mail>')

      -
      -

      Spam Policy

      -
      -

      GET /api/spampolicy/global Get global spam policy

      -
      -
      -

      GET /api/spampolicy/domain/<domain> Get per-domain spam policy

      -
      -
      -

      GET /api/spampolicy/user/<mail> Get per-user spam policy

      -
      -
      -

      DELETE /api/spampolicy/global Delete global spam policy

      -
      -
      -

      DELETE /api/spampolicy/domain/<domain> Delete per-domain spam policy

      -
      -
      -

      DELETE /api/spampolicy/user/<mail> Delete per-user spam policy

      -
      -
      -

      PUT /api/spampolicy/global Set global spam policy Parameters

      -
      -
      -

      PUT /api/spampolicy/domain/<domain> Set per-domain spam policy Parameters

      -
      -
      -

      PUT /api/spampolicy/user/<mail> Set per-user spam policy Parameters

      -
      - -

      Parameters available for global, per-domain, per-user spam policies.

      -
      -

      Per-user policy has the highest priority, then per-domain policy, then global policy.

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      bypass_spam_checksBypass spam checksbypass_spam_checks=yes (default is no)
      bypass_virus_checksBypass virus checksbypass_virus_checks=yes (default is no)
      bypass_banned_checksBypass banned file type checksbypass_banned_checks=yes (default is no)
      bypass_header_checksBypass bad header checksbypass_header_checks=yes (default is no)
      quarantine_spamQuarantine detected spam into SQL databasequarantine_spam=yes (default is no)
      quarantine_virusQuarantine detected virus into SQL databasequarantine_virus=no (default is yes)
      quarantine_bannedQuarantine email with banned file type into SQL databasequarantine_banned=yes (default is no)
      quarantine_bad_headerQuarantine email with bad header into SQL databasequarantine_bad_header=yes (default is no)
      prefix_spam_in_subjectPrefix string [SPAM] in mail subject if it's spamprefix_spam_in_subject=yes (default is no)
      always_insert_x_spam_headersAlways insert X-Spam-* headers in email. It contains spam score and matched SpamAssassin rules. Don't enable this unless you want to debug spam checking.always_insert_x_spam_headers=yes (default is no)
      spam_scoreSet a preferred spam score, if scanned email has higher score than this one, it will be marked as spam.spam_score=4 (defaults to use system setting defined in Amavisd config file.)
      -
      - -
      -

      Throttling

      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      - -

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

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      period *Period of time, in secondsperiod=3600 (one hour)
      msg_sizeMax size of single email, in bytesmsg_size=10485760 (10 MB)
      max_msgsNumber of max inbound emailsmax_msgs=20 (up to 20 messages)
      max_quotaCumulative size of inbound or outbound emails, in bytesmax_quota=1048576000 (1 GB)
      -
      - -
      -

      Greylisting

      -
      -

      GET /api/greylisting/all Get all existing greylisting settings

      -
      -
      -

      GET /api/greylisting/global Get global greylisting setting

      -
      -
      -

      GET /api/greylisting/<domain> Get per-domain greylisting setting

      -
      -
      -

      GET /api/greylisting/<mail> Get per-user greylisting setting

      -
      -
      -

      POST /api/greylisting/global Set global greylisting setting Parameters

      -
      -
      -

      POST /api/greylisting/<domain> Set per-domain greylisting setting Parameters

      -
      -
      -

      POST /api/greylisting/<mail> Set per-user greylisting setting Parameters

      -
      - -

      Parameters available for global, per-domain and per-user greylisting settings.

      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      statusExplicitly enable or disable greylisting service.status=enable (or disable)
      -
      - -
      -
      -

      DELETE /api/greylisting/global Delete global greylisting setting

      -
      -
      -

      DELETE /api/greylisting/<domain> Delete per-domain greylisting setting

      -
      -
      -

      DELETE /api/greylisting/<mail> Delete per-user greylisting setting

      -
      -
      -

      GET /api/greylisting/global/whitelists Get globally whitelisted senders for greylisting service

      -
      -
      -

      GET /api/greylisting/<domain>/whitelists Get whitelisted senders for greylisting service for specified domain

      -
      -
      -

      GET /api/greylisting/<mail>/whitelists Get whitelisted senders for greylisting service for specified user

      -
      -
      -

      POST /api/greylisting/global/whitelists Whitelist senders for greylisting service globally Parameters

      -
      -
      -

      POST /api/greylisting/<domain>/whitelists Whitelist senders for greylisting service for specified domain Parameters

      -
      -
      -

      POST /api/greylisting/<mail>/whitelists Whitelist senders for greylisting services for specified user Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      sendersReset whitelisted senders for global greylisting service to given senders. Multiple addresses must be separated by comma. Conflicts with parameter addSenders and removeSenders.senders=192.168.1.0/24,172.16.10.1,@example.com
      addSendersWhitelist new senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter senders.addSenders=192.168.1.0/24,@example.com
      removeSendersRemove existing whitelisted senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter senders.removeSenders=192.168.1.0/24,@example.com
      -

      Valid sender address formats:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Sender AddressComment
      192.168.2.10Single IP address
      192.168.1.0/24CIDR network
      user@example.comSingle email address
      @example.comEntire domain
      @.example.comEntire domain and all its sub-domains
      -
      - -
      -
      -

      POST /api/greylisting/whitelist_spf_domains Whitelist IP addresses and networks listed in SPF/MX DNS record of given sender domains for greylisting service globally Parameters

      -
      - -

      Given sender domain names are not used directly while checking whitelisting, instead, there's a cron job to query SPF and MX DNS records of given sender domains, then whitelist the IP addresses/networks listed in DNS records.

      -

      Multiple domains must be separated by comma.

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      domainsReset whitelisted sender domains for global greylisting service to given sender domains. Conflicts with parameters addDomains and removeDomains.domains=iredmail.org,gmail.com
      addDomainsAdd new whitelist sender domains for global greylisting service. Conflicts with parameter domains.addDomains=iredmail.org,gmail.com
      removeDomainsRemove existing whitelisted sender domains for global greylisting service. Conflicts with parameter domains.removeDomains=iredmail.org,gmail.com
      - - -
      - -
      -

      Export Accounts

      -

      LDIF (LDAP backend only)

      -
      -

      GET /api/ldif/domain/<domain> Export domain to LDIF

      -
      -
      -

      GET /api/ldif/catchall/<domain> Export per-domain catch-all account to LDIF

      -
      -
      -

      GET /api/ldif/admin/<mail> Export (separated) domain admin to LDIF

      -
      -
      -

      GET /api/ldif/user/<mail> Export mail user to LDIF

      -
      -
      -

      GET /api/ldif/maillist/<mail> Export mailing list account to LDIF

      -
      -
      -

      GET /api/ldif/alias/<mail> Export mail alias account to LDIF

      -
      -

      ChangeLog

      -

      iRedAdmin-Pro-SQL-2.8.0, iRedAdmin-Pro-LDAP-3.0

      -
        -
      • NEW: Able to list all managed domains (/domains).
        • -
      • NEW: Able to manage per-usre enabled mail services (/user/).
        • -
      • NEW: Able to promote mail user to be a global admin (/user/).
        • -
      • -

        Enhancement: Return managed domain names while getting user (must - have admin privilege) or admin profile.

        -
        • -
      • -

        Fixed issues:

        -
          -
        • It always requires password while updating domain admin profile.
          • -
        -
        • -
      • -

        iRedAdmin-Pro-LDAP-3.0:

        -
          -
        • -

          LDAP attribute 'accountSetting' is now converted to a Python dictionary in returned JSON.

          -
            -
          • Old value: {'accountSetting': ['create_new_domains:yes', 'create_max_domains:5', ...], ...}
            • -
          • New value: {'accountSetting': {'create_new_domains': 'yes', 'create_max_domains': 5, ...}}
            • -
          -
          • -
        -
        • -
      -

      iRedAdmin-Pro-SQL-2.7.0, iRedAdmin-Pro-LDAP-2.9.0

      -
        -
      • New: Able to manage global, per-domain and per-user greylisting settings, - whitelist senders, and global whitelisted SPF domains.
        • -
      • iRedAdmin-Pro-SQL-2.7.0:
          -
        • Variable names changed in returned JSON data of user profile (GET /api/user/<mail>):
            -
          • name forwarding is replaced by forwardings, and it's now a list - object of user forwarding email addresses (was a string, multiple - addresses were separated by comma).
            • -
          -
          • -
        • Variable names in returned JSON data of mail alias profile (GET /api/alias/<mail>):
            -
          • name islist is gone.
            • -
          • name goto is replaced by members, and it's now a list object of - member email addresses (was a string, multiple addresses were separated - by comma).
            • -
          -
          • -
        • Variable names in returned JSON data of domain profile (GET /api/domain/<domain>):
            -
          • name catchall always presents, and it's now a list object of catch-all - email address (was a string, multiple addresses were separated by comma).
            • -
          -
          • -
        • Fixed bugs:
            -
          • Cannot set per-user alias addresses while creating new mail user.
            • -
          • Cannot add or remove per-user alias addresses while updating user profile.
            • -
          • User mailbox quota was removed while updating user profile.
            • -
          • Not use default transport setting while creating new domain.
            • -
          -
          • -
        -
        • -
      -

      iRedAdmin-Pro-SQL-2.6.0, iRedAdmin-Pro-LDAP-2.8.0

      -
        -
      • Variable names in returned JSON data has been changed to: - {'_success': ..., '_msg': ...} (was {'success': ..., 'msg': ...}).
        • -
      • Some variable names have been renamed:
          -
        • cn -> name.
          • -
        • mailQuota -> quota
          • -
        • preferredLanguage -> language
          • -
        -
        • -
      - - -
      -

      All documents are available in BitBucket repository, and published under Creative Commons license. You can download the latest version for offline reading. 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.upcoming.html b/html/iredadmin-pro.restful.api.upcoming.html deleted file mode 100644 index 2afc1fad..00000000 --- a/html/iredadmin-pro.restful.api.upcoming.html +++ /dev/null @@ -1,1593 +0,0 @@ - - - - - iRedAdmin-Pro: RESTful API - - - - -

      iRedAdmin-Pro: RESTful API

      -
      - -
      -
      -

      Attention

      -
        -
      • This document is applicable to iRedAdmin-Pro-SQL-2.7.0 and - iRedAdmin-Pro-LDAP-2.9.0. If you're running an old release, please - upgrade iRedAdmin-Pro to the latest release, or check - document for old releases.
        • -
      • If you need an API which has not yet been implemented, don't hesitate to - contact us.
        • -
      -
      -

      Summary

      -

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

      -
        -
      • If operation succeed:
          -
        • For http POST, DELETE, PUT methods, it returns JSON data: {'_success': true}.
          • -
        • For http GET method, it returns JSON data: {'_success': true, '_data': <program_output>}.
          • -
        -
        • -
      • If operation failed, it returns JSON data: {'_success': false, '_msg': '<error_reason>'}.
        • -
      -

      Enable RESTful API

      -
      -

      iRedAdmin-Pro config file location

      -
        -
      • on RHEL/CentOS, it's /var/www/iredadmin/settings.py.
        • -
      • on Debian/Ubuntu, it's /opt/www/iredadmin/settings.py (in recent iRedMail releases) or /usr/share/apache2/iredadmin/settings.py (in old iRedMail releases).
        • -
      • on FreeBSD, it's /usr/local/www/iredadmin/settings.py.
        • -
      • on OpenBSD, it's /var/www/iredadmin/settings.py.
        • -
      -
      -

      RESTful API is disabled by default, to enable it, please add setting below in -iRedAdmin-Pro config file settings.py:

      -
      ENABLE_RESTFUL_API = True
-
      - -

      To restrict API access to few IP addresses, please also add settings below in -iRedAdmin-Pro config file:

      -
      # Enable restriction
-RESTRICT_API_ACCESS = True
-
-# List all IP addresses of allowed client for API access.
-RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
-
      - -

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

      -

      Sample code to interact with iRedAdmin-Pro RESTful API

      - -

      APIs

      -

      Notes:

      -
        -
      • Parameter name with a * mark means the parameter is required, otherwise is optional.
        • -
      • replace <domain> in URL by the real domain name. e.g. example.com
        • -
      • replace <mail> in URL by the real email address. e.g. user@domain.com
        • -
      • replace <number> in URL by an integer number. e.g. 30, 200
        • -
      -

      -

      Login

      -
      -

      POST /api/login Login with an admin username (full email address) and password Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      usernameAdmin username. Must be a full email address.username=admin@mydomain.com
      password(Plain) admin password.password=AsTr0ng@
      -
      - -
      -

      Domain

      -
      -

      GET /api/domain/<domain> Get profile of an existing domain

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameShort description of this domain name. e.g. company namename=Google Inc
      quotaPer-domain mailbox quota, in MB.quota=2048
      languageDefault preferred language for newly created mail userlanguage=en_US
      transportTransport programtransport=dovecot
      defaultQuotaDefault per-user mailbox quota for newly created user, in MB.defaultQuota=1024
      maxUserQuotaMax mailbox quota of a mail user, in MB.maxUserQuota=2048
      numberOfUsersMax number of mail user accountsnumberOfUsers=20
      numberOfAliasesMax number of mail alias accountsnumberOfAliases=30
      numberOfListsMax number of mailing list accounts (Available in LDAP backends)numberOfLists=40
      senderBccPer-domain sender bccsenderBcc=user@domain.com
      recipientBccPer-domain recipient bccrecipientBcc=user@domain.com
      -
      - -
      -
      -

      DELETE /api/domain/<domain> Delete an existing domain (all mail messages will NOT be removed)

      -
      -
      -

      DELETE /api/domain/<domain>/keep_mailbox_days/<number> Delete domain, and keep all mail messages for given days

      -
      -
      -

      PUT /api/domain/<domain> Update profile of an existing domain Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameShort description of this domain name. e.g. company namename=Google Inc
      accountStatusEnable or disable domain. Possible values: active, disabled.accountStatus=active
      quotaMailbox quota for whole domain, in MB.quota=2048
      languageDefault preferred language for newly created mail userlanguage=en_US
      transportTransport programtransport=dovecot
      minPasswordLengthMinimal password lengthminPasswordLength=8
      maxPasswordLengthMaximum password lengthminPasswordLength=20
      defaultQuotaDefault per-user mailbox quota for newly created userdefaultQuota=1024
      maxUserQuotaMax mailbox quota of a mail usermaxUserQuota=2048
      numberOfUsersMax number of mail user accountsnumberOfUsers=20
      numberOfAliasesMax number of mail alias accountsnumberOfAliases=30
      senderBccPer-domain sender bcc addresssenderBcc=user@domain.com
      recipientBccPer-domain recipient bcc addressrecipientBcc=user@domain.com
      is_backupmxMark domain as Backup MX. Must be used with parameter primarymx. Conflicts with parameter transport.is_backupmx=yes (or no)
      primarymxHostname or IP address of primary MX, smtp port number is optional. Must be used with parameter is_backupmx. Conflicts with parameter transport.primarymx=202.96.134.133, primarymx=[mail.iredmail.org]:25
      catchallPer-domain catch-all account (a list of email addresses used to receive emails sent to non-existing addresses under same domain). Multiple addresses must be separated by comma. Set an empty value to disable catch-all support.catchall=user@domain.com,user2@domain.com or catchall= (disable catch-all)
      outboundRelayPer-domain outbound relay. Set an empty value to disable outbound relay.outboundRelay=smtp:[192.168.1.2]:25 or outboundRelay= (disable outbound relay)
      enableServiceEnable new services. Multiple services must be separated by comma. Available services are listed below.enableService=self-service
      disableServiceDisable existing services. Multiple services must be separated by comma. Available services are listed below.disableService=self-service
      removeAllServicesDisable all services (including mail service)removeAllServices= (empty value)
      disableDomainProfiledisable given domain profiles. Normal admin cannot view and update disabled profiles in domain profile page. Available domain profiles are listed below.disableDomainProfile=bcc,relay,aliases
      enableDomainProfileenable given domain profiles. Normal admin can view and update disabled profiles in domain profile page. Available domain profiles are listed below.enableDomainProfile=bcc,relay,aliases
      disableUserProfiledisable given user profiles. Normal admin cannot view and update disabled profiles in user profile page. Available user profiles are listed below.disableUserProfile=bcc,relay,aliases
      enableUserProfileenable given domain profiles. Normal admin can view and update disabled profiles in user profile page. Available user profiles are listed below.enableUserProfile=bcc,relay,aliases
      disableUserPreferencedisable given user preferences in self-service page. Normal mail user cannot view and update disabled preferences. Available user preferences are listed below.disableUserPreference=forwarding,wblist
      enableUserPreferencedisable given user preferences in self-service page. Normal mail user can view and update disabled preferences. Available user preferences are listed below.enableUserProfile=forwarding,wblist
      -

      Available mail services:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      self-serviceEnable self-service for the mail domain.
      mailAll mail services. (LDAP backends only)
      domainaliasAlias domain support. (LDAP backends only)
      senderbccPer-domain sender bcc. (LDAP backends only)
      recipientbccPer-domain recipient bcc. (LDAP backends only)
      -

      Available domain profiles:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      bccPer-domain sender bcc and recipient bcc
      relayPer-domain inbound relay and outbound relay
      catchallPer-domain catchall account
      aliasesAlias domains
      throttlePer-domain inbound and outbound throttling
      greylistingPer-domain greylisting service
      wblistPer-domain whitelists and blacklists
      spampolicyPer-domain spam policy
      backupmxBackup MX
      advancedSome extra settings
      -

      Available user profiles:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      bccPer-user sender bcc and recipient bcc
      forwardingPer-user mail forwarding addresses
      relayPer-user inbound relay and outbound relay
      aliasesPer-user alias addresses
      throttlePer-user inbound and outbound throttling
      greylistingPer-user greylisting service
      wblistPer-user whitelists and blacklists
      spampolicyPer-user spam policy
      -

      Available user preferences (self-service):

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ProfileComment
      personal_infoName, time zone, preferred language of web UI
      forwardingPer-user mail forwarding addresses
      wblistPer-user whitelists and blacklists
      quarantineManage quarantined mails
      rcvd_mailsView basic info of received mails, and whitelist/blacklist mail sender directly.
      spampolicyPer-user spam policy
      -
      - -
      -
      -

      PUT /api/domain/admins/<domain> Manage normal domain admins. Parameters

      -
      - -
      -

      Attention

      -

      Normal domain admin can only promote mail users under managed domains -to be a domain admin.

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      addAdminAdd new domain admins. Multiple services must be separated by comma.addAdmin=one@domain.com,two@domain.com
      removeAdminRemove existing domain admins. Multiple services must be separated by comma.removeAdmin=one@domain.com,two@domain.com
      removeAllAdminsRemove all existing domain admins.removeAllAdmins= (empty value)
      -
      - -
      -

      Domain Admin

      -
      -

      Attention

      -
        -
      • This is standalone domain admin account, not mail user with admin privileges.
        • -
      • Only global admin can access these APIs.
        • -
      -
      -
      -

      GET /api/admin/<mail> Get profile of an existing domain admin

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My Admin Name
      passwordPasswordpassword=AsTr0ng@
      accountStatusEnable or disable account. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      isGlobalAdminMark this admin as global adminisGlobalAdmin=yes
      -

      Below parameters are used by normal domain admin (isGlobalAdmin=no). With isGlobalAdmin=yes, these parameters will be discarded.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      maxDomainshow many mail domains this admin can createmaxDomains=5
      maxQuotahow much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter quotaUnit. Sample: 10TB, 20GB, 100MB.maxQuota=2
      quotaUnitQuota unit used by maxQuota parameter. Must be used with parameter maxQuota. Possible values: TB, GB, MB.quotaUnit=TB
      maxUsershow many mail users this admin can create. It's shared by all domains created/managed by this admin.maxUsers=100
      maxAliaseshow many mail aliases this admin can create. It's shared by all domains created/managed by this admin.maxAliases=200
      maxListshow many mailing lists this admin can create. It's shared by all domains created/managed by this admin.maxLists=300
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My Admin Name
      passwordPasswordpassword=AsTr0ng@
      accountStatusEnable or disable account. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      isGlobalAdminMark this admin as global adminisGlobalAdmin=yes
      -

      Below parameters are used by normal domain admin (isGlobalAdmin=no). With isGlobalAdmin=yes, these parameters will be discarded.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      maxDomainshow many mail domains this admin can createmaxDomains=5
      maxQuotahow much mailbox quota this admin can create. Quota is shared by all domains created/managed by this admin. Must be used with parameter quotaUnit. Sample: 10TB, 20GB, 100MB.maxQuota=2
      quotaUnitQuota unit used by maxQuota parameter. Must be used with parameter maxQuota. Possible values: TB, GB, MB.quotaUnit=TB
      maxUsershow many mail users this admin can create. It's shared by all domains created/managed by this admin.maxUsers=100
      maxAliaseshow many mail aliases this admin can create. It's shared by all domains created/managed by this admin.maxAliases=200
      maxListshow many mailing lists this admin can create. It's shared by all domains created/managed by this admin.maxLists=300
      -
      - -
      -
      -

      POST /api/verify_password/admin/<mail> Verify given (plain) password against the one stored in SQL/LDAP Parameters

      -
      - -
      -

      Attention

      -

      Password verification is limited to global domain admin.

      -
      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      passwordPlain passwordpassword=u0tBF82cIV@vi8Gme
      -
      - -
      -

      Mail User

      -
      -

      GET /api/user/<mail> Get profile of an existing mail user

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My New Name
      passwordPasswordpassword=AsTr0ng@
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      quotaMailbox quota (in MB)quota=1024
      -
      - -
      -
      -

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

      -
      -
      -

      DELETE /api/user/<mail>/keep_mailbox_days/<number> Delete an existing mail user, and keep the mailbox for given days. Defaults to 100 years.

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My New Name
      passwordPasswordpassword=u0tBF82cIV@vi8Gme
      quotaMailbox quota (in MB)quota=1024
      accountStatusEnable or disable user. Possible values: active, disabled.accountStatus=active
      languagePreferred language of iRedAdmin web UIlanguage=en_US
      employeeidUser ID (or Employee Number)employeeid=My Employee ID
      transportTransport programtransport=dovecot
      forwardingPer-user mail forwarding. Multiple addresses must be separated by comma. To save an email copy in mailbox, add original email address as one of forwarding addresses.forwarding=user1@domain.com,user2@domain.com,user3@domain.com
      aliasesPer-user alias addresses. Multiple addresses must be separated by comma. If empty, all per-user alias addresses owned by this user will be removed. Conflicts with parameter addAlias and removeAlias.aliases=user1@domain.com,user2@domain.com,user3@domain.com
      addAliasAdd new per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter aliases.aliases=user1@domain.com,user2@domain.com,user3@domain.com
      removeAliasRemove existing per-user alias addresses. Multiple addresses must be separated by comma. Conflicts with parameter aliases.aliases=user1@domain.com,user2@domain.com,user3@domain.com
      -
      - -
      -
      -

      POST /api/user/<mail>/change_email/<new_mail> Change user's email address (from '<mail>' to '<new_mail>')

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterComment
      accountStatusAccount status. Possible value is: active, disabled.
      passwordPassword
      languagePreferred language of iRedAdmin web UI
      transportPer-user transport
      -
      - -
      -
      -

      POST /api/verify_password/user/<mail> Verify given (plain) password against the one stored in SQL/LDAP Parameters

      -
      - -
      -

      Attention

      -

      Password verification is limited to global domain admin.

      -
      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      passwordPlain passwordpassword=u0tBF82cIV@vi8Gme
      -
      - -
      -

      Mailing List

      -
      -

      Attention

      -

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

      -
      -
      -

      GET /api/maillist/<mail> Get profile of an existing mailing list account

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mailing list. Multiple members must be separated by comma.members=user1@domain.com,user2@domain.com
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      namedisplay namename=My List Name
      accessPolicyDefines who can send email to this mailing listaccessPolicy=public
      membersMembers of mailing list. Multiple members must be separated by comma. Conflict with parameter addMember and removeMember.members=user1@domain.com,user2@domain.com
      addMemberAdd new members of mailing list. Multiple members must be separated by comma. Conflict with parameter members.addMember=user1@domain.com,user2@domain.com
      removeMemberRemove existing members of mailing list. Multiple members must be separated by comma. Conflict with parameter members.removeMember=user1@domain.com,user2@domain.com
      -
      - -
      -

      Mail Alias

      -
      -

      GET /api/alias/<mail> Get profile of an existing mail alias

      -
      -
      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mail alias. Multiple members must be separated by comma.members=user1@domain.com,user2@domain.com
      -
      -

      Attention

      -

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

      -
      -
      - -
      -
      -

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

      -
      -
      -

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

      -
      - -
      -

      Attention

      -

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

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      nameDisplay namename=My List Name
      accessPolicyDefines who can send email to this mail alias accountaccessPolicy=public
      membersMembers of mail alias. Multiple members must be separated by comma. Conflict with parameter addMember and removeMember.members=user1@domain.com,user2@domain.com
      addMemberAdd new members of mail alias. Multiple members must be separated by comma. Conflict with parameter members.addMember=user1@domain.com,user2@domain.com
      removeMemberRemove existing members of mail alias. Multiple members must be separated by comma. Conflict with parameter members.removeMember=user1@domain.com,user2@domain.com
      -
      - -
      -
      -

      POST /api/alias/<mail>/change_email/<new_mail> Change email address of alias account (from '<mail>' to '<new_mail>')

      -
      -

      Spam Policy

      -
      -

      GET /api/spampolicy/global Get global spam policy

      -
      -
      -

      GET /api/spampolicy/domain/<domain> Get per-domain spam policy

      -
      -
      -

      GET /api/spampolicy/user/<mail> Get per-user spam policy

      -
      -
      -

      DELETE /api/spampolicy/global Delete global spam policy

      -
      -
      -

      DELETE /api/spampolicy/domain/<domain> Delete per-domain spam policy

      -
      -
      -

      DELETE /api/spampolicy/user/<mail> Delete per-user spam policy

      -
      -
      -

      PUT /api/spampolicy/global Set global spam policy Parameters

      -
      -
      -

      PUT /api/spampolicy/domain/<domain> Set per-domain spam policy Parameters

      -
      -
      -

      PUT /api/spampolicy/user/<mail> Set per-user spam policy Parameters

      -
      - -

      Parameters available for global, per-domain, per-user spam policies.

      -
      -

      Per-user policy has the highest priority, then per-domain policy, then global policy.

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      bypass_spam_checksBypass spam checksbypass_spam_checks=yes (default is no)
      bypass_virus_checksBypass virus checksbypass_virus_checks=yes (default is no)
      bypass_banned_checksBypass banned file type checksbypass_banned_checks=yes (default is no)
      bypass_header_checksBypass bad header checksbypass_header_checks=yes (default is no)
      quarantine_spamQuarantine detected spam into SQL databasequarantine_spam=yes (default is no)
      quarantine_virusQuarantine detected virus into SQL databasequarantine_virus=no (default is yes)
      quarantine_bannedQuarantine email with banned file type into SQL databasequarantine_banned=yes (default is no)
      quarantine_bad_headerQuarantine email with bad header into SQL databasequarantine_bad_header=yes (default is no)
      prefix_spam_in_subjectPrefix string [SPAM] in mail subject if it's spamprefix_spam_in_subject=yes (default is no)
      always_insert_x_spam_headersAlways insert X-Spam-* headers in email. It contains spam score and matched SpamAssassin rules. Don't enable this unless you want to debug spam checking.always_insert_x_spam_headers=yes (default is no)
      spam_scoreSet a preferred spam score, if scanned email has higher score than this one, it will be marked as spam.spam_score=4 (defaults to use system setting defined in Amavisd config file.)
      -
      - -
      -

      Throttling

      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      -
      -

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

      -
      - -

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

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      period *Period of time, in secondsperiod=3600 (one hour)
      msg_sizeMax size of single email, in bytesmsg_size=10485760 (10 MB)
      max_msgsNumber of max inbound emailsmax_msgs=20 (up to 20 messages)
      max_quotaCumulative size of inbound or outbound emails, in bytesmax_quota=1048576000 (1 GB)
      -
      - -
      -

      Greylisting

      -
      -

      GET /api/greylisting/all Get all existing greylisting settings

      -
      -
      -

      GET /api/greylisting/global Get global greylisting setting

      -
      -
      -

      GET /api/greylisting/<domain> Get per-domain greylisting setting

      -
      -
      -

      GET /api/greylisting/<mail> Get per-user greylisting setting

      -
      -
      -

      POST /api/greylisting/global Set global greylisting setting Parameters

      -
      -
      -

      POST /api/greylisting/<domain> Set per-domain greylisting setting Parameters

      -
      -
      -

      POST /api/greylisting/<mail> Set per-user greylisting setting Parameters

      -
      - -

      Parameters available for global, per-domain and per-user greylisting settings.

      - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      statusExplicitly enable or disable greylisting service.status=enable (or disable)
      -
      - -
      -
      -

      DELETE /api/greylisting/global Delete global greylisting setting

      -
      -
      -

      DELETE /api/greylisting/<domain> Delete per-domain greylisting setting

      -
      -
      -

      DELETE /api/greylisting/<mail> Delete per-user greylisting setting

      -
      -
      -

      GET /api/greylisting/global/whitelists Get globally whitelisted senders for greylisting service

      -
      -
      -

      GET /api/greylisting/<domain>/whitelists Get whitelisted senders for greylisting service for specified domain

      -
      -
      -

      GET /api/greylisting/<mail>/whitelists Get whitelisted senders for greylisting service for specified user

      -
      -
      -

      POST /api/greylisting/global/whitelists Whitelist senders for greylisting service globally Parameters

      -
      -
      -

      POST /api/greylisting/<domain>/whitelists Whitelist senders for greylisting service for specified domain Parameters

      -
      -
      -

      POST /api/greylisting/<mail>/whitelists Whitelist senders for greylisting services for specified user Parameters

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      sendersReset whitelisted senders for global greylisting service to given senders. Multiple addresses must be separated by comma. Conflicts with parameter addSenders and removeSenders.senders=192.168.1.0/24,172.16.10.1,@example.com
      addSendersWhitelist new senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter senders.addSenders=192.168.1.0/24,@example.com
      removeSendersRemove existing whitelisted senders for greylisting service globally. Multiple addresses must be separated by comma. Conflicts with parameter senders.removeSenders=192.168.1.0/24,@example.com
      -

      Valid sender address formats:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Sender AddressComment
      192.168.2.10Single IP address
      192.168.1.0/24CIDR network
      user@example.comSingle email address
      @example.comEntire domain
      @.example.comEntire domain and all its sub-domains
      -
      - -
      -
      -

      POST /api/greylisting/whitelist_spf_domains Whitelist IP addresses and networks listed in SPF/MX DNS record of given sender domains for greylisting service globally Parameters

      -
      - -

      Given sender domain names are not used directly while checking whitelisting, instead, there's a cron job to query SPF and MX DNS records of given sender domains, then whitelist the IP addresses/networks listed in DNS records.

      -

      Multiple domains must be separated by comma.

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      ParameterSummarySample Usage
      domainsReset whitelisted sender domains for global greylisting service to given sender domains. Conflicts with parameters addDomains and removeDomains.domains=iredmail.org,gmail.com
      addDomainsAdd new whitelist sender domains for global greylisting service. Conflicts with parameter domains.addDomains=iredmail.org,gmail.com
      removeDomainsRemove existing whitelisted sender domains for global greylisting service. Conflicts with parameter domains.removeDomains=iredmail.org,gmail.com
      - - -
      - -
      -

      Export Accounts

      -

      LDIF (LDAP backend only)

      -
      -

      GET /api/ldif/domain/<domain> Export domain to LDIF

      -
      -
      -

      GET /api/ldif/catchall/<domain> Export per-domain catch-all account to LDIF

      -
      -
      -

      GET /api/ldif/admin/<mail> Export (separated) domain admin to LDIF

      -
      -
      -

      GET /api/ldif/user/<mail> Export mail user to LDIF

      -
      -
      -

      GET /api/ldif/maillist/<mail> Export mailing list account to LDIF

      -
      -
      -

      GET /api/ldif/alias/<mail> Export mail alias account to LDIF

      -
      -

      ChangeLog

      -

      iRedAdmin-Pro-SQL-2.7.0, iRedAdmin-Pro-LDAP-2.9.0

      -
        -
      • New: Able to manage global, per-domain and per-user greylisting settings, - whitelist senders, and global whitelisted SPF domains.
        • -
      • iRedAdmin-Pro-SQL-2.7.0:
          -
        • Variable names changed in returned JSON data of user profile (GET /api/user/<mail>):
            -
          • name forwarding is replaced by forwardings, and it's now a list - object of user forwarding email addresses (was a string, multiple - addresses were separated by comma).
            • -
          -
          • -
        • Variable names in returned JSON data of mail alias profile (GET /api/alias/<mail>):
            -
          • name islist is gone.
            • -
          • name goto is replaced by members, and it's now a list object of - member email addresses (was a string, multiple addresses were separated - by comma).
            • -
          -
          • -
        • Variable names in returned JSON data of domain profile (GET /api/domain/<domain>):
            -
          • name catchall always presents, and it's now a list object of catch-all - email address (was a string, multiple addresses were separated by comma).
            • -
          -
          • -
        • Fixed bugs:
            -
          • Cannot set per-user alias addresses while creating new mail user.
            • -
          • Cannot add or remove per-user alias addresses while updating user profile.
            • -
          • User mailbox quota was removed while updating user profile.
            • -
          • Not use default transport setting while creating new domain.
            • -
          -
          • -
        -
        • -
      -

      iRedAdmin-Pro-SQL-2.6.0, iRedAdmin-Pro-LDAP-2.8.0

      -
        -
      • Variable names in returned JSON data has been changed to: - {'_success': ..., '_msg': ...} (was {'success': ..., 'msg': ...}).
        • -
      • Some variable names have been renamed:
          -
        • cn -> name.
          • -
        • mailQuota -> quota
          • -
        • preferredLanguage -> language
          • -
        -
        • -
      - - -
      -

      All documents are available in BitBucket repository, and published under Creative Commons license. You can download the latest version for offline reading. If you found something wrong, please do contact us to fix it.

      -
      - - \ No newline at end of file