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 iredadmin (if you're running Nginx) or Apache service is required after changed iRedAdmin config file.

iRedAdmin-Pro config file location

To restrict API access to few IP addresses, please login to iRedAdmin-Pro as global admin, then click menu System -> Settings, find option RESTful API is accessible only from specified IP addresses or networks, input the allowed IP addresses or networks.

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

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 0 day which means keeping 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. If parameter primarymx is not given, MTA (Postfix) will query DNS record to get primary mx server. 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)
addAliasDomain Add new alias domains. Multiple services must be separated by comma. addAliasDomain=alias1.com,alias2.com
removeAliasDomain Remove existing alias domains. Multiple services must be separated by comma. removeAllServices=alias1.com,alias2.com
aliasDomains Reset all alias domains. If empty, all existing alias domains will be removed. Conflicts with parameter addAliasDomain and removeAliasDomain. aliasDomains=alias1.com,alias2.com
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
services Reset all services. If empty, all existing services will be removed. services=mail,self-service
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
password_policies Password policies. including min/max password lengths.
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 Parameters

Encrypted account password is not exposed in API request by default, if you want to expose it for some reason, please add a new line in iRedAdmin-Pro config file /opt/www/iredadmin/settings.py like below, then restart iredadmin service:

API_HIDDEN_ADMIN_PROFILES = []

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
disableViewingMailLog Disallow this admin to view log of inbound/outbound mails. disableViewingMailLog=yes (or no)
disableManagingQuarantinedMails Disallow this admin to manage quarantined mails. disableManagingQuarantinedMails=yes (or no)

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
disableViewingMailLog Disallow this admin to view log of inbound/outbound mails. disableViewingMailLog=yes (or no)
disableManagingQuarantinedMails Disallow this admin to manage quarantined mails. disableManagingQuarantinedMails=yes (or no)

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 Parameters

Encrypted account password is not exposed in API request by default, if you want to expose it for some reason, please add a new line in iRedAdmin-Pro config file /opt/www/iredadmin/settings.py like below, then restart iredadmin service:

API_HIDDEN_USER_PROFILES = []

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

Parameter Summary Sample Usage
name Display name name=My New Name
password Plain password. WARNING: Conflict with parameter password_hash. password=AsTr0ng@
password_hash Set user password to the given hashed/encrypted password. NOTE: Since the password is encrypted, iRedAdmin-Pro can not verify it against password policies. WARNING: Conflict with parameter password. password_hash={SSHA}APvI8DhU8Ktstdlye6yVDaypcrfqsUcXk0c7aQ==
language Preferred language of iRedAdmin web UI language=en_US
quota Mailbox quota (in MB) quota=1024
mailboxFormat Mailbox format. e.g. maildir, mdbox. Defaults to maildir if not present. For more details, please read Dovecot document: https://wiki2.dovecot.org/MailboxFormat. WARNING: Changing mailbox format does not migrate the mailbox on file system automatically, you have to migrate it manually. New email will be stored in new mailbox format immediately. mailboxFormat=mdbox
mailboxFolder Mailbox folder name (case sensitive) which will be appended to user's home path. Defaults to Maildir. It's useful if you need to migrate to different mailbox folder. WARNING: New email will be stored in new mailbox folder immediately. mailboxFolder=Maildir
maildir Absolute path of the mailbox. All characters will be converted to lower cases. maildir=/var/vmail/vmail1/example.com/username

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 0 day which means keeping forever.

PUT /api/user/<mail> Update profile of an existing mail user Parameters

Parameter Summary Sample Usage
name Display name name=Michael Jordon
gn Given name gn=Jordon
sn Surname sn=Jeffery
password Set user password to the given one. password=u0tBF82cIV@vi8Gme
password_hash Set user password to the given hashed/encrypted password. NOTE: Since the password is encrypted, iRedAdmin-Pro can not verify it against password plicies. WARNING: Conflict with parameter password. password={SSHA}qjmhvlsofWDu/AvVhOJX1cU/CvYKLYlwlM5bHw==
quota Mailbox quota (in MB). 0 means unlimited. 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 Reset per-user mail forwarding to given (valid) addresses. 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
addForwarding Add per-user mail forwarding addresses. Multiple addresses must be separated by comma. WARNING: Conflict with parameter forwarding. addForwarding=user1@domain.com,user2@domain.com,user3@domain.com
removeForwarding Remove existing per-user mail forwarding addresses. Multiple addresses must be separated by comma. WARNING: Conflict with parameter forwarding. removeForwarding=user1@domain.com,user2@domain.com,user3@domain.com
senderBcc Per-user BCC for outbound emails. Only one email address is allowed. Parameter with empty value will remove existing sender bcc address. senderBcc=user1@domain.com or
senderBcc= (remove existing bcc address)
recipientBcc Per-user BCC for inbound emails. Only one email address is allowed. Parameter with empty value will remove existing recipient bcc address. recipientBcc=user1@domain.com or
recipientBcc= (remove existing bcc address)
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
mailboxFormat Mailbox format. e.g. maildir, mdbox. Defaults to maildir if not present. For more details, please read Dovecot document: https://wiki2.dovecot.org/MailboxFormat. WARNING: Changing mailbox format does not migrate the mailbox on file system automatically, you have to migrate it manually. New email will be stored in new mailbox format immediately. mailboxFormat=mdbox
mailboxFolder Mailbox folder name (case sensitive) which will be appended to user's home path. Defaults to Maildir. It's useful if you need to migrate to different mailbox folder. WARNING: New email will be stored in new mailbox folder immediately. mailboxFolder=Maildir
maildir Absolute path of the mailbox. All characters will be converted to lower cases. maildir=/var/vmail/vmail1/example.com/username
telephoneNumber Telephone number (LDAP backend only) telephoneNumber=12345678,88888888
mobile Mobile phone number (LDAP backend only) mobile=12345678,88888888

Attention

Notes about services, addService, removeService parameters:

  • Available service names in iRedMail:

    • smtp
    • smtpsecured (SMTP over TLS or SSL)
    • smtptls (SMTP over TLS)
    • pop3
    • pop3secured (POP3 over TLS or SSL)
    • pop3tls (POP3 over TLS)
    • imap
    • imapsecured (IMAP over TLS or SSL)
    • imaptls (IMAP over TLS)
    • managesieve
    • managesievesecured (Managesieve over TLS or SSL)
    • managesievetls (Managesieve over TLS)
    • 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>')

GET /api/users/<domain> Get user profiles under given domain Parameters

Parameter Default Value Comment Sample Usage
email_only no Return a list of mail users' email addresses instead of detailed profiles. email_only=yes
disabled_only no Return only disabled mail users. disabled_only=yes

PUT /api/users/<domain> Update profiles of all users under given 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

Subscribable Mailing List

Attention

GET /api/mls/<domain> Get profile of all mailing lists under given domain Parameters

Parameter Sample Usage Default Value Comment
email_only email_only=yes no Return a list of mailing list email addresses instead of detailed profile.

GET /api/ml/<mail> Get profile of an existing mailing list account Parameters

Parameter Sample Usage Default Value Comment
with_subscribers with_subscribers=yes no Get subscribers of mailing list.

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

Parameter Sample Usage Default Value Comment
name name=Sales Team Display name of the mailing list.
accountStatus accountStatus=active Enable or disable account. Possible values: active, disabled.
accessPolicy accessPolicy=membersonly Defines who can send email to this mailing list. Possible values: public, domain, subdomain, membersonly, moderatorsonly.
is_newsletter is_newsletter=yes no Mark this mailing list as a newsletter, to enable subscription/unsubscription from web site.
newsletter_description newsletter_description=short description text The short description text displayed on newsletter subscription page.
close_list close_list=yes no If set to yes, subscription and unsubscription via mail is disabled.
only_moderator_can_post only_moderator_can_post=yes no If set to yes, only moderators are allowed to post to it. The check is made against the From: header.
only_subscriber_can_post only_subscriber_can_post=yes yes If set to yes, only subscribed members are allowed to post to it. The check is made against the From: header.
disable_subscription disable_subscription=yes no If set to yes, subscription is disabled, but unsubscription is still possible.
disable_subscription_confirm disable_subscription_confirm=yes If set to yes, mlmmj won't send mail to subscriber to ask for confirmation to subscribe to the list. WARNING: This should in principle never ever be used, but there are times on local lists etc. where this is useful. HANDLE WITH CARE!
disable_digest_subscription disable_digest_subscription=yes If set to yes, subscription to the digest version of the mailing list is disabled. Useful if you don't want to allow digests and notify users about it.
disable_digest_text disable_digest_text=yes If set to yes, digest mails won't have a text part with a thread summary.
disable_nomail_subscription disable_nomail_subscription=yes If set to yes, subscription to the 'nomail' version of the mailing list is disabled. Useful if you don't want to allow 'nomail' and notify users about it.
moderated moderated=yes no If set to yes. Parameter owner or moderators is required to specify the moderators. Note: moderators has higher priority (means only addresses specified by moderators are act as moderators).
moderate_non_subscriber_post moderate_non_subscriber_post=no no If set to yes, all postings from people who are not allowed to post to the list will be moderated. Default (set to no) is denied.
disable_retrieving_old_posts disable_retrieving_old_posts=yes If set to yes, retrieving old posts by sending email to address <listname>+get-N@ is disabled.
only_subscriber_can_get_old_posts only_subscriber_can_get_old_posts=no yes If set to yes, only subscribers can retrieve old posts by sending email to LISTNAME+get-N@
disable_retrieving_subscribers disable_retrieving_subscribers=yes yes If set to yes, (owner) retrieving subscribers by sending email to LISTNAME+list@ is disabled. Note: only owner can send to such address.
disable_send_copy_to_sender disable_send_copy_to_sender=yes yes If set to yes, senders won't receive copies of their own posts.
notify_owner_when_sub_unsub notify_owner_when_sub_unsub=no no Notify the owner(s) when someone sub/unsubscribing to a mailing list.
notify_sender_when_moderated notify_sender_when_moderated=no no Notify sender (based on the envelope from) when their post is being moderated.
disable_archive disable_archive=yes no If set to yes, emails won't be saved in the archive but simply deleted.
moderate_subscription moderate_subscription=yes no If set to yes, subscription will be moderated by owner(s) or moderators specified by subscription_moderators. Moderators specified by subscription_moderators has higher priority. If set to no, subscription is not moderated, also, all moderators which were specified by subscription_moderators will be removed.
extra_addresses extra_addresses=extra1@domain.com,extra2@domain.com Define extra addresses of the mailing list.
subscription_moderators subscription_moderators=<mail1>,<mail2>,<mail3> Specify subscription moderators. Note: if subscription_moderators is given, moderate_subscription will be set to yes automatically. If no valid moderators are given, subscription will be moderated by owner(s).
owner owner=<mail1>,<mail2>,<mail3> Define owner(s) of the mailing list. Owners will get mails sent to <listname>+owner@<domain.com>.
moderators moderators=<mail1>,<mail2> Specify moderators of the mailing list. Set to empty value will remove all existing moderators.
max_message_size max_message_size=10240 Specify max mail message size in bytes.
subject_prefix subject_prefix=[prefix text] Add a prefix in the Subject: line of mails sent to the list. Set to empty value to remove it.
custom_headers custom_headers=<header1>:<value1>\n<header2>:<value2> Add custom headers to every mail coming through. Multiple headers must be separated by \n. Set empty value to remove it. Note: mlmmjadmin will always add X-Mailing-List: <mail> and Reply-To: <mail> for each mailing list account.
remove_headers remove_headers=Message-ID,Received Remove given mail headers. NOTE: either header: or header (without :) is ok. Note: mlmmjadmin will always remove DKIM-Signature: and Authentication-Results:.
name name=Short description of list Set a short description of the mailing list account.
footer_text footer_text=footer in plain text Append footer (in plain text format) to every email sent to the list.
footer_html footer_text=<p>footer in html</p> Append footer (in html format) to every email sent to the list.

Parameters used to add subscribers:

Parameter Sample Usage Default Value Comment
subscribers subscribers=<mail1>,<mail2>,<mail3>,... Subscribe users to mailing list. Multiple subscribers must be separated by comma.
require_confirm require_confirm=no yes Send email to subscribers and let subscribers confirm the subscription.
subscription subscription=normal normal Subscribe to different subscription. Valid values are: normal, digest, nomail.

DELETE /api/ml/<mail> Delete an existing mailing list Parameters

Parameter Summary Sample Usage
keep_archive Archive account settings and messages before deleting the mailing list. keep_archive=no

PUT /api/ml/<mail> Update profile of an existing mailing list Parameters

Parameters used to add subscribers:

Parameter Sample Usage Default Value Comment
add_subscribers add_subscribers=<mail1>,<mail2>,<mail3>,... Subscribe users to mailing list. Multiple subscribers must be separated by comma.
require_confirm require_confirm=no yes Send email to subscribers and let subscribers confirm the subscription.
subscription subscription=normal normal Subscribe to different subscription. Valid values are: normal, digest, nomail.

Parameters used to remove subscribers:

Parameter Sample Usage Default Value Comment
remove_subscribers remove_subscribers=<mail1>,<mail2>,<mail3>,... Remove existing subscribers from mailing list. Multiple subscribers must be separated by comma.

Other parameters:

Parameter Sample Usage Default Value Comment
name name=Sales Team Display name of the mailing list.
accountStatus accountStatus=active Enable or disable account. Possible values: active, disabled.
accessPolicy accessPolicy=membersonly Defines who can send email to this mailing list. Possible values: public, domain, subdomain, membersonly, moderatorsonly.
is_newsletter is_newsletter=yes no Mark this mailing list as a newsletter, to enable subscription/unsubscription from web site.
newsletter_description newsletter_description=short description text The short description text displayed on newsletter subscription page.
close_list close_list=yes no If set to yes, subscription and unsubscription via mail is disabled.
only_moderator_can_post only_moderator_can_post=yes no If set to yes, only moderators are allowed to post to it. The check is made against the From: header.
only_subscriber_can_post only_subscriber_can_post=yes yes If set to yes, only subscribed members are allowed to post to it. The check is made against the From: header.
disable_subscription disable_subscription=yes no If set to yes, subscription is disabled, but unsubscription is still possible.
disable_subscription_confirm disable_subscription_confirm=yes If set to yes, mlmmj won't send mail to subscriber to ask for confirmation to subscribe to the list. WARNING: This should in principle never ever be used, but there are times on local lists etc. where this is useful. HANDLE WITH CARE!
disable_digest_subscription disable_digest_subscription=yes If set to yes, subscription to the digest version of the mailing list is disabled. Useful if you don't want to allow digests and notify users about it.
disable_digest_text disable_digest_text=yes If set to yes, digest mails won't have a text part with a thread summary.
disable_nomail_subscription disable_nomail_subscription=yes If set to yes, subscription to the 'nomail' version of the mailing list is disabled. Useful if you don't want to allow 'nomail' and notify users about it.
moderated moderated=yes no If set to yes. Parameter owner or moderators is required to specify the moderators. Note: moderators has higher priority (means only addresses specified by moderators are act as moderators).
moderate_non_subscriber_post moderate_non_subscriber_post=no no If set to yes, all postings from people who are not allowed to post to the list will be moderated. Default (set to no) is denied.
disable_retrieving_old_posts disable_retrieving_old_posts=yes If set to yes, retrieving old posts by sending email to address <listname>+get-N@ is disabled.
only_subscriber_can_get_old_posts only_subscriber_can_get_old_posts=no yes If set to yes, only subscribers can retrieve old posts by sending email to LISTNAME+get-N@
disable_retrieving_subscribers disable_retrieving_subscribers=yes yes If set to yes, (owner) retrieving subscribers by sending email to LISTNAME+list@ is disabled. Note: only owner can send to such address.
disable_send_copy_to_sender disable_send_copy_to_sender=yes yes If set to yes, senders won't receive copies of their own posts.
notify_owner_when_sub_unsub notify_owner_when_sub_unsub=no no Notify the owner(s) when someone sub/unsubscribing to a mailing list.
notify_sender_when_moderated notify_sender_when_moderated=no no Notify sender (based on the envelope from) when their post is being moderated.
disable_archive disable_archive=yes no If set to yes, emails won't be saved in the archive but simply deleted.
moderate_subscription moderate_subscription=yes no If set to yes, subscription will be moderated by owner(s) or moderators specified by subscription_moderators. Moderators specified by subscription_moderators has higher priority. If set to no, subscription is not moderated, also, all moderators which were specified by subscription_moderators will be removed.
extra_addresses extra_addresses=extra1@domain.com,extra2@domain.com Define extra addresses of the mailing list.
subscription_moderators subscription_moderators=<mail1>,<mail2>,<mail3> Specify subscription moderators. Note: if subscription_moderators is given, moderate_subscription will be set to yes automatically. If no valid moderators are given, subscription will be moderated by owner(s).
owner owner=<mail1>,<mail2>,<mail3> Define owner(s) of the mailing list. Owners will get mails sent to <listname>+owner@<domain.com>.
moderators moderators=<mail1>,<mail2> Specify moderators of the mailing list. Set to empty value will remove all existing moderators.
max_message_size max_message_size=10240 Specify max mail message size in bytes.
subject_prefix subject_prefix=[prefix text] Add a prefix in the Subject: line of mails sent to the list. Set to empty value to remove it.
custom_headers custom_headers=<header1>:<value1>\n<header2>:<value2> Add custom headers to every mail coming through. Multiple headers must be separated by \n. Set empty value to remove it. Note: mlmmjadmin will always add X-Mailing-List: <mail> and Reply-To: <mail> for each mailing list account.
remove_headers remove_headers=Message-ID,Received Remove given mail headers. NOTE: either header: or header (without :) is ok. Note: mlmmjadmin will always remove DKIM-Signature: and Authentication-Results:.
name name=Short description of list Set a short description of the mailing list account.
footer_text footer_text=footer in plain text Append footer (in plain text format) to every email sent to the list.
footer_html footer_text=<p>footer in html</p> Append footer (in html format) to every email sent to the list.

Mailing List (Unsubscribable)

Attention

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 Parameters

Parameter Summary Sample Usage
archive Archive subscribable mailing list before deleting the account. NOTE: This option is only applicable to the subscribable mailing list account. archive=no

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
accountStatus Enable or disable domain. Valid values: active, disabled. accountStatus=active
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/aliases/<domain> Get mail aliases' profiles under given domain Parameters

Parameter Default Value Comment Sample Usage
email_only no Return a list of mail aliases' email addresses instead of detailed profiles. email_only=yes
disabled_only no Return only disabled mail aliases. disabled_only=yes

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)

Whitelisting and Blacklisting

Valid whitelisting and blacklisting addresses. Invalid addresses will be discarded silently.

Address Examples
Single IP Address 192.168.2.10
IP CIDR Network 192.168.2.0/24, 2620:0:2d0:200::7/128
Single email address user@domain.ltd
Entire email domain @domain.ltd
Entire email domain and all its sub-domains @.domain.ltd
Catch-all address @.


GET /api/wblist/inbound/whitelist/global Get global whitelists for inbound.

GET /api/wblist/inbound/blacklist/global Get global blacklists for inbound.

GET /api/wblist/outbound/whitelist/global Get global whitelists for outbound.

GET /api/wblist/outbound/blacklist/global Get global whitelists for outbound.

GET /api/wblist/inbound/whitelist/<domain> Get per-domain whitelists for inbound.

GET /api/wblist/inbound/blacklist/<domain> Get per-domain blacklists for inbound.

GET /api/wblist/outbound/whitelist/<domain> Get per-domain whitelists for outbound.

GET /api/wblist/outbound/blacklist/<domain> Get per-domain whitelists for outbound.

GET /api/wblist/inbound/whitelist/<mail> Get per-user whitelists for inbound.

GET /api/wblist/inbound/blacklist/<mail> Get per-user blacklists for inbound.

GET /api/wblist/outbound/whitelist/<mail> Get per-user whitelists for outbound.

GET /api/wblist/outbound/blacklist/<mail> Get per-user whitelists for outbound.

POST /api/wblist/inbound/whitelist/global Add new global whitelists for inbound. Parameters

POST /api/wblist/inbound/blacklist/global Add new global blacklists for inbound. Parameters

POST /api/wblist/outbound/whitelist/global Add new global whitelists for outbound. Parameters

POST /api/wblist/outbound/blacklist/global Add new global whitelists for outbound. Parameters

POST /api/wblist/inbound/whitelist/<domain> Add new per-domain whitelists for inbound. Parameters

POST /api/wblist/inbound/blacklist/<domain> Add new per-domain blacklists for inbound. Parameters

POST /api/wblist/outbound/whitelist/<domain> Add new per-domain whitelists for outbound. Parameters

POST /api/wblist/outbound/blacklist/<domain> Add new per-domain whitelists for outbound. Parameters

POST /api/wblist/inbound/whitelist/<mail> Add new per-user whitelists for inbound. Parameters

POST /api/wblist/inbound/blacklist/<mail> Add new per-user blacklists for inbound. Parameters

POST /api/wblist/outbound/whitelist/<mail> Add new per-user whitelists for outbound. Parameters

POST /api/wblist/outbound/blacklist/<mail> Add new per-user whitelists for outbound. Parameters

Parameters available for global, per-domain and per-user whitelist/blacklist settings.

Parameter Summary Sample Usage
addresses The addresses you want to whitelist or blacklist.
Multiple addresses must be separated by comma.		 addresses=user1@domain.com,192.168.1.10

PUT /api/wblist/inbound/whitelist/global Delete given global whitelists for inbound. Parameters

PUT /api/wblist/inbound/blacklist/global Delete given existing global blacklists for inbound. Parameters

PUT /api/wblist/outbound/whitelist/global Delete given existing global whitelists for outbound. Parameters

PUT /api/wblist/outbound/blacklist/global Delete given existing global whitelists for outbound. Parameters

PUT /api/wblist/inbound/whitelist/<domain> Delete given per-domain whitelists for inbound. Parameters

PUT /api/wblist/inbound/blacklist/<domain> Delete given per-domain blacklists for inbound. Parameters

PUT /api/wblist/outbound/whitelist/<domain> Delete given per-domain whitelists for outbound. Parameters

PUT /api/wblist/outbound/blacklist/<domain> Delete given per-domain whitelists for outbound. Parameters

PUT /api/wblist/inbound/whitelist/<mail> Delete given per-user whitelists for inbound. Parameters

PUT /api/wblist/inbound/blacklist/<mail> Delete given per-user blacklists for inbound. Parameters

PUT /api/wblist/outbound/whitelist/<mail> Delete given per-user whitelists for outbound. Parameters

PUT /api/wblist/outbound/blacklist/<mail> Delete given per-user whitelists for outbound. Parameters

Parameters available for global, per-domain and per-user whitelist/blacklist settings.

Parameter Summary Sample Usage
addresses The addresses you want to whitelist or blacklist.
Multiple addresses must be separated by comma.		 addresses=user1@domain.com,192.168.1.10

DELETE /api/wblist/inbound/whitelist/global Delete all existing global whitelists for inbound.

DELETE /api/wblist/inbound/blacklist/global Delete all existing global blacklists for inbound.

DELETE /api/wblist/outbound/whitelist/global Delete all existing global whitelists for outbound.

DELETE /api/wblist/outbound/blacklist/global Delete all existing global whitelists for outbound.

DELETE /api/wblist/inbound/whitelist/<domain> Delete all per-domain global whitelists for inbound.

DELETE /api/wblist/inbound/blacklist/<domain> Delete all per-domain global blacklists for inbound.

DELETE /api/wblist/outbound/whitelist/<domain> Delete all per-domain existing global whitelists for outbound.

DELETE /api/wblist/outbound/blacklist/<domain> Delete all per-domain existing global whitelists for outbound.

DELETE /api/wblist/inbound/whitelist/<mail> Delete all per-user existing global whitelists for inbound.

DELETE /api/wblist/inbound/blacklist/<mail> Delete all per-user existing global blacklists for inbound.

DELETE /api/wblist/outbound/whitelist/<mail> Delete all per-user existing global whitelists for outbound.

DELETE /api/wblist/outbound/blacklist/<mail> Delete all per-user existing global whitelists for outbound.

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.