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

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)

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

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

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

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

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