REST API
The plugin exposes a small REST API under Modoboa's versioned API, mounted at:
/api/v2/virtualhosts/
/api/v2/shared-mailboxes/Authenticate the same way you would for any other Modoboa v2 API call. While the plugin is not activated, every endpoint answers 403 with {"code": "license_required"}.
Virtual hosts
These endpoints require the Django model permissions on the VirtualHost model (in practice, a super administrator).
INFO
Virtual hosts are created by assigning a hostname to a domain through the domain API/forms, not through this API — there is no POST /virtualhosts/ create endpoint. See Virtual hosts.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v2/virtualhosts/ | List virtual hosts. Supports pagination, ordering (name, creation) and search (by name). |
DELETE | /api/v2/virtualhosts/{id}/ | Delete a virtual host (removes its Nginx config asynchronously). |
GET | /api/v2/virtualhosts/for_domain/{domain_pk}/ | Return the virtual host linked to a given domain. |
POST | /api/v2/virtualhosts/{id}/retry_provisioning/ | Re-run the provisioning chain. Valid only when the host is failed (else 409 Conflict). |
POST | /api/v2/virtualhosts/{id}/set_state/ | Enable/disable a host. Body: `{"enabled": true |
GET | /api/v2/virtualhosts/{id}/theme/ | Read the host's theme overrides. |
PUT | /api/v2/virtualhosts/{id}/theme/ | Update theme colors (partial payload — omitted fields are left untouched). |
POST | /api/v2/virtualhosts/{id}/theme_logo/ | Upload a logo. Multipart body: logo_type + image. |
DELETE | /api/v2/virtualhosts/{id}/theme_logo/?logo_type=... | Clear a logo. |
Virtual host representation
GET responses for a virtual host include:
| Field | Description |
|---|---|
pk | Identifier. |
name | Hostname. |
creation | Creation timestamp. |
enabled | Whether the host is enabled. |
domains | Linked domains (pk + name). |
has_certificate | Whether a certificate exists on disk. |
certificate_valid_until | Certificate expiry, if any. |
provisioning_status | pending, ready or failed. |
last_provisioning_error | Error message recorded on the last failure (empty otherwise). |
Global settings
The plugin's global parameters (the ACME and Nginx settings from Configuration) are read and written through Modoboa's standard parameters API, the same way the Parameters panel does:
GET /api/v2/parameters/virtualhosts/
PUT /api/v2/parameters/virtualhosts/Logo types
The logo_type value used by the theme_logo endpoints is one of:
login— login page logo;menu— left-menu logo;creation_form— creation-form logo.
See Theming for what each logo controls.
Shared mailboxes
These endpoints are open to super administrators, resellers and domain administrators (the admin.change_mailbox permission), who only get the shared mailboxes of the domains they administer. See Shared mailboxes.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v2/shared-mailboxes/ | List shared mailboxes. Supports pagination, ordering (mailbox__address, mailbox__domain__name), search (address or domain) and domain (a domain id). |
POST | /api/v2/shared-mailboxes/ | Create a new account and share it. Body: {"address", "name", "quota"} (quota in MB, the default quota of the domain when missing). |
POST | /api/v2/shared-mailboxes/convert/ | Share an existing account. Body: {"mailbox": <mailbox id>}. Only simple user accounts authenticated by Modoboa can be shared. |
GET | /api/v2/shared-mailboxes/{id}/ | Retrieve a shared mailbox. |
DELETE | /api/v2/shared-mailboxes/{id}/ | Stop sharing: the account and its messages are kept. |
POST | /api/v2/shared-mailboxes/{id}/resync/ | Apply the rights of the members again (202 Accepted). |
GET | /api/v2/shared-mailboxes/{id}/members/ | List the members. |
POST | /api/v2/shared-mailboxes/{id}/members/ | Add a member. Body: {"member": <mailbox id>, "level", "can_send_as"}. |
PATCH | /api/v2/shared-mailboxes/{id}/members/{member_id}/ | Change the level or can_send_as of a member. |
DELETE | /api/v2/shared-mailboxes/{id}/members/{member_id}/ | Remove a member. |
level is one of read, write and manage (see Members). Members must belong to the domain of the shared mailbox.
Shared mailbox representation
| Field | Description |
|---|---|
id | Identifier. |
mailbox | Id of the mailbox of the account. |
address | Address of the shared mailbox. |
name | Name of the account. |
domain | Id of its domain. |
members_count | Number of members. |
sync_status | pending, ready or failed: status of the last application of the rights. |
last_sync | When the rights were last applied. |
last_sync_error | Error recorded on the last failure (empty otherwise). |
Accounts API
The accounts API of Modoboa (/api/v2/accounts/) tells which accounts are shared mailboxes: each account gets a shared_mailbox field ({"id", "sync_status"}, null for other accounts) and a modoboa_pro.shared_mailbox badge, which also filters the list (?badge=modoboa_pro.shared_mailbox).