iRedAdmin-Pro: RESTful API

Note

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

iRedAdmin-Pro: RESTful API

Summary

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

If operation succeed, iRedAdmin-Pro returns JSON data: {'success': true}.
If operation failed, iRedAdmin-Pro returns JSON data: {'success': false, 'msg': '<error_reason>'}.

Requirements

At least iRedAdmin-Pro-SQL-2.4.0 or iRedAdmin-Pro-LDAP-2.6.0. Earlier releases didn't offer RESTful API.

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:

Parameter name with a * mark means the parameter is required, otherwise is optional.
replace <domain> in URL by the real domain name.
replace <mail> in URL by the real email address.

Domain

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

Parameter Name	Summary	Sample Usage
`cn`	Short description of this domain name. e.g. company name	`cn=Google Inc`
`quota`	Per-domain mailbox quota, in MB.	`quota=2048`
`language`	Default preferred language for newly created mail user	`language=en_US`
`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 (LDAP only)	`numberOfLists=40`

DELETE /api/domain/<domain> Delete an existing domain

User

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

Parameter Name	Summary	Sample Usage
`cn`	Display name	`cn=My New Name`
`password`	Password	`password=AsTr0ng@`
`language`	Preferred language of web UI	`language=en_US`
`quota`	Mailbox quota (in MB)	`quota=1024`

DELETE /api/user/<mail> Delete an existing mail user

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

Parameter Name	Summary	Sample Usage
`cn`	Display name	`cn=My New Name`
`language`	Preferred language of web UI	`language=en_US`
`transport`	Transport program	`transport=dovecot`

PUT /api/user/<mail>/password Update user's password upcoming Parameters

Parameter Name	Comment
`password`	Password

PUT /api/users/<domain> Update profiles of all users under domain upcoming Parameters

Parameter Name	Comment
accountStatus	Account status. Possible value is: active, disabled.
language	Preferred language of web UI
transport	Per-user transport

PUT /api/users/<domain>/password Update passwords of all users under domain upcoming Parameters

Parameter Name	Comment
`password`	Password

Mailing List

Attention

Mailing list is only available in OpenLDAP backend. For SQL backends, please use mail alias account as mailing list.

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

DELETE /api/maillist/<mail> Delete an existing mailing list

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

Parameter Name	Summary	Sample Usage
`cn`	display name	`cn=My List Name`
`accessPolicy`	Defines who can send email to this mailing list	`accessPolicy=public`

Mail Alias

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

DELETE /api/alias/<mail> Delete an existing mail alias

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

Parameter Name	Summary	Sample Usage
`cn`	display name	`cn=My List Name`
`accessPolicy`	Defines who can send email to this mail alias account	`accessPolicy=public`

Note: accessPolicy for mail alias account is only available for SQL backends.

Throttling

GET /api/throttle/global/inbound Get global inbound throttle settings

POST /api/throttle/global/inbound Set global inbound throttle settings Parameters

GET /api/throttle/global/outbound Get global outbound throttle settings

POST /api/throttle/global/outbound Set global inbound throttle settings Parameters

GET /api/throttle/<domain>/inbound Get domain inbound throttle settings

POST /api/throttle/<domain>/inbound Set domain inbound throttle settings Parameters

GET /api/throttle/<domain>/outbound Get domain outbound throttle settings

POST /api/throttle/<domain>/outbound Set domain outbound throttle settings Parameters

GET /api/throttle/<mail>/inbound Get user inbound throttle settings

POST /api/throttle/<mail>/inbound Set user inbound throttle settings Parameters

GET /api/throttle/<mail>/outbound Get user outbound throttle settings

POST /api/throttle/<mail>/outbound Set user outbound throttle settings Parameters

Parameters available for global, per-domain, per-user throttle settings.

Parameter Name	Summary	Sample Usage
`period` *	Period of time, in seconds	`period=3600` (one hour)
`msg_size`	Max size of single email, in bytes	`msg_size=10485760` (10 MB)
`max_msgs`	Number of max inbound emails	`max_msgs=20` (up to 20 messages)
`max_quota`	Cumulative size of inbound or outbound emails, in bytes	`max_quota=1048576000` (1 GB)

Export Accounts

LDIF (LDAP backend only)

GET /api/ldif/domain/<domain> Export domain to LDIF upcoming

GET /api/ldif/catchall/<domain> Export per-domain catch-all account to LDIF upcoming

GET /api/ldif/admin/<mail> Export (separated) domain admin to LDIF upcoming

GET /api/ldif/user/<mail> Export mail user to LDIF upcoming

GET /api/ldif/maillist/<mail> Export mailing list account to LDIF upcoming

GET /api/ldif/alias/<mail> Export mail alias account to LDIF upcoming