Note
If you need an API which has not yet been implemented, don't hesitate to contact us.
{'_success': ..., '_msg': ...}
(was {'success': ..., 'msg': ...}
).cn
-> name
.mailQuota
-> quota
preferredLanguage
-> language
iRedAdmin-Pro RESTful API will return message in JSON format.
POST
, DELETE
, PUT
actions, it returns JSON data: {'_success': true}
.GET
action, it returns JSON data: {'_success': true, '_data': <program_output>}
.{'_success': false, '_msg': '<error_reason>'}
.RESTful API is disabled by default, to enable it, please add setting below in
iRedAdmin-Pro config file settings.py
:
ENABLE_RESTFUL_API = True
To restrict API access to few IP addresses, please also add settings below in iRedAdmin-Pro config file:
# Enable restriction
RESTRICT_API_ACCESS = True
# List all IP addresses of allowed client for API access.
RESTFUL_API_CLIENTS = ['172.16.244.1', ...]
Restarting Apache or uwsgi (if you're running Nginx) is required.
Notes:
*
mark means the parameter is required, otherwise is optional.<domain>
in URL by the real domain name. e.g. example.com
<mail>
in URL by the real email address. e.g. user@domain.com
<number>
in URL by an integer number. e.g. 30
, 200
GET
/api/domain/<domain>
Get profile of an existing domain
upcoming
POST
/api/domain/<domain>
Create a new domain
Parameters
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 |
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
upcoming
PUT
/api/domain/<domain>
Update profile of an existing domain
upcoming
Parameters
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) |
GET
/api/domain/services/<domain>
Get/List all enabled per-domain services
upcoming
PUT
/api/domain/services/<domain>
Manage enabled per-domain services
upcoming
Parameters
Parameter | Summary | Sample Usage |
---|---|---|
enableService |
Enable new services. Multiple services must be separated by comma. | enableService=sogo,vpn,xmpp |
disableService |
Disable existing services. Multiple services must be separated by comma. | disableService=sogo,vpn,xmpp |
removeAllServices |
Disable all services (including mail service) | removeAllServices= (empty value) |
PUT
/api/domain/admins/<domain>
Manage normal domain admins.
upcoming
Parameters
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) |
Attention
GET
/api/admin/<mail>
Get profile of an existing domain admin
upcoming
POST
/api/admin/<mail>
Create a new domain admin
upcoming
Parameters
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 |
DELETE
/api/admin/<mail>
Delete an existing domain admin
upcoming
PUT
/api/admin/<mail>
Update profile of an existing domain admin
upcoming
Parameters
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 |
POST
/api/verify_password/admin/<mail>
Verify given (plain) password against the one stored in SQL/LDAP
upcoming
Parameters
Attention
Password verification is limited to global domain admin.
Parameter | Summary | Sample Usage |
---|---|---|
password |
Plain password | password=u0tBF82cIV@vi8Gme |
GET
/api/user/<mail>
Get profile of an existing mail user
upcoming
POST
/api/user/<mail>
Create a new mail user
Parameters
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 |
DELETE
/api/user/<mail>
Delete an existing mail user
PUT
/api/user/<mail>
Update profile of an existing mail user
Parameters
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 |
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 . |
aliases=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 . |
aliases=user1@domain.com,user2@domain.com,user3@domain.com |
POST
/api/user/<mail>/change_email/<new_mail>
Change user's email address (from '<mail>' to '<new_mail>')
PUT
/api/users/<domain>
Update profiles of all users under domain
upcoming
Parameters
Parameter | Comment |
---|---|
accountStatus |
Account status. Possible value is: active, disabled. |
password |
Password |
language |
Preferred language of iRedAdmin web UI |
transport |
Per-user transport |
POST
/api/verify_password/user/<mail>
Verify given (plain) password against the one stored in SQL/LDAP
upcoming
Parameters
Attention
Password verification is limited to global domain admin.
Parameter | Summary | Sample Usage |
---|---|---|
password |
Plain password | password=u0tBF82cIV@vi8Gme |
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
upcoming
POST
/api/maillist/<mail>
Create a new mailing list
upcoming
Parameters
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 |
DELETE
/api/maillist/<mail>
Delete an existing mailing list
PUT
/api/maillist/<mail>
Update profile of an existing mailing list
Parameters
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 |
GET
/api/alias/<mail>
Get profile of an existing mail alias
upcoming
POST
/api/alias/<mail>
Create a new mail alias
upcoming
Parameters
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.
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.
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 |
POST
/api/alias/<mail>/change_email/<new_mail>
Change email address of alias account (from '<mail>' to '<new_mail>')
GET
/api/spampolicy/global
Get global spam policy
upcoming
PUT
/api/spampolicy/global
Set global spam policy
upcoming
Parameters
DELETE
/api/spampolicy/global
Delete global spam policy
upcoming
GET
/api/spampolicy/domain/<domain>
Get per-domain spam policy
upcoming
PUT
/api/spampolicy/domain/<domain>
Set per-domain spam policy
upcoming
Parameters
DELETE
/api/spampolicy/domain/<domain>
Delete per-domain spam policy
upcoming
GET
/api/spampolicy/user/<mail>
Get per-user spam policy
upcoming
PUT
/api/spampolicy/user/<mail>
Set per-user spam policy
upcoming
Parameters
DELETE
/api/spampolicy/user/<mail>
Delete per-user spam policy
upcoming
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.) |
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.
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) |
GET
/api/ldif/domain/<domain>
Export domain to LDIF
upcoming
GET
/api/ldif/catchall/<domain>
Export per-domain catch-all account to LDIF
upcoming
GET
/api/ldif/admin/<mail>
Export (separated) domain admin to LDIF
upcoming
GET
/api/ldif/user/<mail>
Export mail user to LDIF
upcoming
GET
/api/ldif/maillist/<mail>
Export mailing list account to LDIF
upcoming
GET
/api/ldif/alias/<mail>
Export mail alias account to LDIF
upcoming