iRedAdmin-Pro: RESTful API

Attention

Check out the lightweight on-premises email archiving software developed by iRedMail team: Spider Email Archiver.

Attention

Summary

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

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

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:

Login

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

Parameter Summary Sample Usage
username Admin 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

Parameter Summary Sample Usage
name_only Return only mail domain names name_only=yes
disabled_only Return only disabled mail domains disabled_only=yes

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

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. Defaults to keep forever.

PUT /api/domain/<domain> Update profile of an existing domain 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)
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

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.

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

POST /api/admin/<mail> Create a new domain admin 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

PUT /api/admin/<mail> Update profile of an existing domain admin 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 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

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

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

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

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

POST /api/maillist/<mail> Create a new mailing list 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

POST /api/alias/<mail> Create a new mail alias 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

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.

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)

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.

Parameter Summary Sample Usage
status Explicitly 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

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

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.

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

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

All documents are available in GitHub 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.