diff --git a/en_US/iredadmin/0-iredadmin-pro.restful.api-20170824.md b/en_US/iredadmin/0-iredadmin-pro.restful.api-20170824.md new file mode 100644 index 00000000..9ea9c06f --- /dev/null +++ b/en_US/iredadmin/0-iredadmin-pro.restful.api-20170824.md @@ -0,0 +1,688 @@ +# 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: + * 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, + 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/0-iredadmin-pro.restful.api.new.md b/en_US/iredadmin/0-iredadmin-pro.restful.api.new.md new file mode 100644 index 00000000..980f76fa --- /dev/null +++ b/en_US/iredadmin/0-iredadmin-pro.restful.api.new.md @@ -0,0 +1,695 @@ +# iRedAdmin-Pro: RESTful API + +[TOC] + +!!! attention + + * This document is applicable to `iRedAdmin-Pro-SQL-2.9.0` and + `iRedAdmin-Pro-LDAP-3.1`. 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) + `addService` | Enable new services. Multiple services must be separated by comma. Available services are listed below. | `addService=self-service` + `removeService` | Disable existing services. Multiple services must be separated by comma. Available services are listed below. | `removeService=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.9.0, iRedAdmin-Pro-LDAP-3.1 + +* Parameter names changed: + * While updating domain profile (`PUT /api/domain/`): + * `enableService` was renamed to `addService` + * `disableService` was renamed to `removeService` + +### 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, + 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/upgrade/2-iredadmin-pro.releases.md b/en_US/upgrade/2-iredadmin-pro.releases.md index ffd6442b..eb9990c4 100644 --- a/en_US/upgrade/2-iredadmin-pro.releases.md +++ b/en_US/upgrade/2-iredadmin-pro.releases.md @@ -22,7 +22,8 @@ this tutorial with just one shell command: Version | Release Date | Comment | Extra ---|---|---|--- -[2.9.0](http://www.iredmail.org/forum/topic12946.html) | Jul 1, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api.html) +[3.0](http://www.iredmail.org/forum/topic13212.html) | Aug 24, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api.html) +[2.9.0](http://www.iredmail.org/forum/topic12946.html) | Jul 1, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api-20170824.html) [2.8.0](http://www.iredmail.org/forum/topic12499.html) | Mar 21, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) [2.7.0](http://www.iredmail.org/forum/topic12266.html) | Jan 23, 2017 | Improved RESTful API support. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) [2.6.1](http://www.iredmail.org/forum/topic11809.html) | Oct 10, 2016 | Fixes an __CRITICAL SECURITY ISSUE__ on FreeBSD and OpenBSD. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) @@ -55,7 +56,8 @@ Version | Release Date | Comment | Extra Version | Release Date | Comment | RESTful API Document ---|---|---|--- -[2.7.0](http://www.iredmail.org/forum/topic12945.html) | Jul 1, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api.html) +[2.8.0](http://www.iredmail.org/forum/topic13213.html) | Aug 24, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api.html) +[2.7.0](http://www.iredmail.org/forum/topic12945.html) | Jul 1, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api-20170824.html) [2.6.0](http://www.iredmail.org/forum/topic12498.html) | Mar 21, 2017 | Bug fix release. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) [2.5.0](http://www.iredmail.org/forum/topic12267.html) | Jan 23, 2017 | Improved RESTful API support. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) [2.4.1](http://www.iredmail.org/forum/topic11809.html) | Oct 10, 2016 | Fixes an __CRITICAL SECURITY ISSUE__ on FreeBSD and OpenBSD. | [RESTful API document](./iredadmin-pro.restful.api-20170123.html) diff --git a/html/iredadmin-pro.releases.html b/html/iredadmin-pro.releases.html index 3676a792..cd631bb7 100644 --- a/html/iredadmin-pro.releases.html +++ b/html/iredadmin-pro.releases.html @@ -56,10 +56,16 @@ this tutorial with just one shell command:

+3.0 +Aug 24, 2017 +Bug fix release. +RESTful API document + + 2.9.0 Jul 1, 2017 Bug fix release. -RESTful API document +RESTful API document 2.8.0 @@ -237,10 +243,16 @@ this tutorial with just one shell command:

+2.8.0 +Aug 24, 2017 +Bug fix release. +RESTful API document + + 2.7.0 Jul 1, 2017 Bug fix release. -RESTful API document +RESTful API document 2.6.0 diff --git a/html/iredadmin-pro.restful.api-20170824.html b/html/iredadmin-pro.restful.api-20170824.html new file mode 100644 index 00000000..b78a5361 --- /dev/null +++ b/html/iredadmin-pro.restful.api-20170824.html @@ -0,0 +1,1704 @@ + + + + + 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/<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, + 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
    • +
    +
  • +
+ + + + + \ No newline at end of file diff --git a/html/iredadmin-pro.restful.api.new.html b/html/iredadmin-pro.restful.api.new.html new file mode 100644 index 00000000..a3ab6c6a --- /dev/null +++ b/html/iredadmin-pro.restful.api.new.html @@ -0,0 +1,1716 @@ + + + + + iRedAdmin-Pro: RESTful API + + + + +

iRedAdmin-Pro: RESTful API

+ +
+

Attention

+
    +
  • This document is applicable to iRedAdmin-Pro-SQL-2.9.0 and + iRedAdmin-Pro-LDAP-3.1. 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)
addServiceEnable new services. Multiple services must be separated by comma. Available services are listed below.addService=self-service
removeServiceDisable existing services. Multiple services must be separated by comma. Available services are listed below.removeService=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.9.0, iRedAdmin-Pro-LDAP-3.1

+
    +
  • Parameter names changed:
      +
    • While updating domain profile (PUT /api/domain/<domain>):
        +
      • enableService was renamed to addService
      • +
      • disableService was renamed to removeService
      • +
      +
    • +
    +
  • +
+

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, + 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
    • +
    +
  • +
+ + + + + \ No newline at end of file