iRedAdmin-Pro: RESTful API

Note

If you need an API which has not yet been implemented, don't hesitate to contact us.

ChangeLog

Summary

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

Requirements

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

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

# Enable restriction
RESTRICT_API_ACCESS = True

# List all IP addresses of allowed client for API access.
RESTFUL_API_CLIENTS = ['172.16.244.1', ...]

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

Sample code to interact with iRedAdmin-Pro RESTful API

APIs

Notes:

Domain

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

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

Parameter Name 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 Name 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 Name 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 Name 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

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 Name Summary Sample Usage
name Display name name=My Admin Name
password Password password=AsTr0ng@
language Preferred language of iRedAdmin web UI language=en_US
domainGlobalAdmin Mark this admin as global admin domainGlobalAdmin=yes

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

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 Name Summary Sample Usage
password Plain password password=u0tBF82cIV@vi8Gme

Mail User

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

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

Parameter Name 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 Name 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 Name 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 Name Summary Sample Usage
password Plain password password=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 upcoming

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

Parameter Name 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 Name 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

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

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

Parameter Name 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 Name 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>')

Spam Policy

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 Name 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

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 Name 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)

Export Accounts

LDIF (LDAP backend only)

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

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