Files
mailcow-dockerized/data/web/api/openapi.yaml
T

16297 lines
529 KiB
YAML

openapi: 3.1.0
info:
description: >-
The API of mailcow, the mail server suite with antispam, antivirus and a
web UI.
**API keys**: create them in the mailcow UI under System > Configuration >
Access > Administrators, card API. A key works from its allowed IP
addresses (or from anywhere if the IP check is skipped). Read-only keys
may use the `get` routes only. Keys set in mailcow.conf (`API_KEY`,
`API_KEY_READ_ONLY`, `API_ALLOW_FROM`) are shown in the UI but can only be
changed in mailcow.conf. A key acts as an administrator.
**Requests**: `get` routes use GET, all others POST with
`Content-Type: application/json`.
- add: the new object as body
- edit: `{"items": [...], "attr": {...}}`, `items` are the objects to
change, `attr` the values to set
- delete: the list of objects to delete
**Answers**: write routes return the list of messages of the call
(`type`, `msg`), or `{"type": "success", "msg": "Task completed"}` /
`{"type": "error", "msg": "Cannot add item"}` if there are none. The
status is 200 for failures too, so check `type`. Read routes return the
object or list, `{}` or `[]` if there is nothing. Unknown routes answer
404, invalid JSON 400, a wrong method 405.
title: mailcow API
version: "1.0.0"
servers:
- url: /
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
schemas:
Message:
type: object
description: >-
One message of a write call, as the mailcow UI shows it. `msg` is a key
of the mailcow language files, alone or as a list with the values of its
placeholders.
properties:
type:
type: string
enum:
- success
- danger
- warning
- info
log:
type: array
description: >-
The call that produced the message (function, action, object,
data), secrets replaced by `*`
items: {}
msg:
oneOf:
- type: string
- type: array
items: {}
required:
- type
- msg
Messages:
type: array
items:
$ref: "#/components/schemas/Message"
TaskResult:
type: object
description: Answer of a write call that produced no message
properties:
type:
type: string
enum:
- success
- error
msg:
type: string
examples:
- Task completed
- Cannot add item
required:
- type
- msg
Error:
type: object
properties:
type:
type: string
const: error
msg:
type: string
required:
- type
- msg
Domain:
type: object
description: >-
A domain. Quotas and sizes are in bytes; the `*_int` fields repeat the
value before them.
properties:
domain_name:
type: string
description: Domain name (IDN as punycode)
domain_h_name:
type: string
description: Domain name in Unicode
description:
type: string
description: Description
max_new_mailbox_quota:
type: integer
description: >-
Largest quota a new mailbox can get: the free domain quota, at most
the max. mailbox quota
def_new_mailbox_quota:
type: integer
description: Quota a new mailbox gets by default
quota_used_in_domain:
type: [string, integer]
description: Sum of the quotas of the mailboxes
bytes_total:
type: [string, integer]
description: Storage used by the mailboxes
msgs_total:
type: [string, integer]
description: Number of messages in the mailboxes
mboxes_in_domain:
type: integer
description: Number of mailboxes
mboxes_left:
type: integer
description: Mailboxes that can still be added
max_num_aliases_for_domain:
type: integer
description: Max. number of aliases
max_num_mboxes_for_domain:
type: integer
description: Max. number of mailboxes
def_quota_for_mbox:
type: integer
description: Default quota of new mailboxes
max_quota_for_mbox:
type: integer
description: Max. quota per mailbox
max_quota_for_domain:
type: integer
description: Quota of the whole domain
relayhost:
type: [string, integer]
description: ID of the sender-dependent transport, "0" = none
backupmx:
type: integer
enum: [0, 1]
description: Relay domain (backup MX)
backupmx_int:
type: integer
enum: [0, 1]
gal:
type: integer
enum: [0, 1]
description: Global address list in SOGo
gal_int:
type: integer
enum: [0, 1]
rl:
description: Rate limit, `false` if none
oneOf:
- $ref: "#/components/schemas/DomainRatelimit"
- type: boolean
const: false
active:
type: integer
enum: [0, 1]
description: Domain active
active_int:
type: integer
enum: [0, 1]
relay_all_recipients:
type: integer
enum: [0, 1]
description: Relay all recipients
relay_all_recipients_int:
type: integer
enum: [0, 1]
relay_unknown_only:
type: integer
enum: [0, 1]
description: Relay non-existing mailboxes only
relay_unknown_only_int:
type: integer
enum: [0, 1]
archive:
type: integer
enum: [0, 1]
description: Mails of the mailboxes set to `inherit` are archived
created:
type: string
description: Creation time (`YYYY-MM-DD hh:mm:ss`)
modified:
type: [string, "null"]
description: Time of the last change
aliases_in_domain:
type: [integer, string]
description: Number of aliases, including those of its alias domains
aliases_left:
type: integer
description: Aliases that can still be added
domain_admins:
type: string
description: Comma-separated domain admins, `-` if none; admins only
tags:
type: array
items:
type: string
description: Tags; missing when the domain has none
DomainRatelimit:
type: object
description: Rate limit of a domain or alias domain
properties:
value:
type: string
description: Messages per time frame
frame:
type: string
enum: [s, m, h, d]
description: Time frame (second, minute, hour, day)
DomainTemplate:
type: object
properties:
id:
type: integer
description: Template ID
template:
type: string
description: Template name
type:
type: string
const: domain
attributes:
$ref: "#/components/schemas/DomainTemplateAttributes"
created:
type: string
description: Creation time
modified:
type: [string, "null"]
description: Time of the last change
DomainTemplateAttributes:
type: object
description: Values of a domain template as stored; quotas in bytes
properties:
tags:
type: array
items:
type: string
max_num_aliases_for_domain:
type: integer
max_num_mboxes_for_domain:
type: integer
def_quota_for_mbox:
type: integer
max_quota_for_mbox:
type: integer
max_quota_for_domain:
type: integer
rl_frame:
type: string
enum: [s, m, h, d]
rl_value:
type: [string, integer]
description: Rate limit, "" = none
active:
type: integer
enum: [0, 1]
gal:
type: integer
enum: [0, 1]
backupmx:
type: integer
enum: [0, 1]
archive:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Archive mails of mailboxes set to `inherit`
relay_all_recipients:
type: integer
enum: [0, 1]
relay_unknown_only:
type: integer
enum: [0, 1]
dkim_selector:
type: string
key_size:
type: integer
DomainTemplateInput:
type: object
description: >-
Values of a domain template, quotas in MiB. The defaults apply when a
template is added; for edit/domain/template see there.
properties:
template:
type: string
description: Template name, unique
tags:
type: array
items:
type: string
default: []
description: Tags of new domains
max_num_aliases_for_domain:
type: [integer, string]
default: 400
description: Max. number of aliases
max_num_mboxes_for_domain:
type: [integer, string]
default: 10
description: Max. number of mailboxes
def_quota_for_mbox:
type: [integer, string]
default: 3072
description: Default quota of new mailboxes in MiB
max_quota_for_mbox:
type: [integer, string]
default: 10240
description: Max. quota per mailbox in MiB
max_quota_for_domain:
type: [integer, string]
default: 10240
description: Quota of the whole domain in MiB
rl_value:
type: [integer, string]
default: ""
description: Rate limit, messages per `rl_frame`; empty = none
rl_frame:
type: string
enum: [s, m, h, d]
default: s
description: Rate limit time frame
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 1
gal:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 1
description: Global address list in SOGo
backupmx:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Relay domain (backup MX)
archive:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Archive mails of mailboxes set to `inherit`
relay_all_recipients:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
relay_unknown_only:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
dkim_selector:
type: string
default: dkim
description: Selector of the DKIM key of new domains
key_size:
type: [integer, string]
default: 2048
description: DKIM key size in bits of new domains
AliasDomain:
type: object
properties:
alias_domain:
type: string
description: Alias domain name
target_domain:
type: string
description: Domain the alias domain points to
parent_is_backupmx:
type: integer
enum: [0, 1]
description: The target domain is a relay domain
active:
type: integer
enum: [0, 1]
description: Alias domain active
active_int:
type: integer
enum: [0, 1]
rl:
description: Rate limit, `false` if none
oneOf:
- $ref: "#/components/schemas/DomainRatelimit"
- type: boolean
const: false
created:
type: string
description: Creation time
modified:
type: [string, "null"]
description: Time of the last change
DomainPolicyEntry:
type: object
properties:
object:
type: string
description: The domain or mailbox the entry belongs to
value:
type: string
description: Sender address or pattern
prefid:
type: integer
description: Entry ID (for delete/domain-policy)
DkimKey:
type: object
properties:
pubkey:
type: string
description: Public key (base64, without PEM lines)
length:
type: string
enum: ["1024", "2048", "3072", "4096", ">= 8192"]
description: Key size in bits, estimated from the public key
dkim_txt:
type: string
description: >-
Content of the DNS TXT record; split into quoted strings of 255
characters when `SPLIT_DKIM_255` is enabled
dkim_selector:
type: string
description: Selector
privkey:
type: string
description: >-
Private key in PEM format, base64-encoded, when
`SHOW_DKIM_PRIV_KEYS` is enabled, else empty
DomainSearchRequest:
type: object
description: >-
Server-side processing parameters of DataTables
(https://datatables.net/manual/server-side). Without `start` and
`length` all matching domains are answered.
properties:
draw:
type: integer
description: Request counter, answered as it is
start:
type: integer
description: Offset of the first domain
length:
type: integer
description: Number of domains, -1 = all
search:
type: object
properties:
value:
type: string
description: Searched in all columns with `searchable` true
order:
type: array
items:
type: object
properties:
column:
type: integer
description: Position in `columns` (see the description of the route)
dir:
type: string
enum: [asc, desc]
columns:
type: array
description: >-
The columns of the table; the position gives the database column
(see the description of the route)
items:
type: object
properties:
data:
type: [string, integer]
description: >-
Column name of the UI; a column position makes
`search.value` of this entry filter that column
searchable:
type: [boolean, string]
description: Column takes part in the global search; must be set
orderable:
type: [boolean, string]
description: Column may be sorted by; must be set
search:
type: object
properties:
value:
type: string
description: Filter of this column
DomainSearchResult:
type: object
properties:
draw:
type: integer
description: "`draw` of the request"
recordsTotal:
type: integer
description: Number of domains the caller can see
recordsFiltered:
type: integer
description: Number of domains that match the search
data:
type: array
description: The domains of the page
items:
$ref: "#/components/schemas/Domain"
MailboxItems:
description: One mailbox address or a list of them
oneOf:
- type: string
- type: array
items:
type: string
UserAclName:
type: string
description: "A user ACL: something the mailbox user may do in the UI"
enum:
- spam_alias
- tls_policy
- spam_score
- spam_policy
- delimiter_action
- syncjobs
- eas_reset
- sogo_profile_reset
- pushover
- quarantine
- quarantine_attachments
- quarantine_notification
- quarantine_category
- app_passwds
- pw_reset
ProtocolAccessName:
type: string
enum:
- imap
- pop3
- smtp
- sieve
- eas
- dav
MailboxAttributes:
type: object
description: Settings of a mailbox; flags are "0" or "1"
properties:
force_pw_update:
type: [string, integer]
description: The user must change the password at the next login
force_tfa:
type: [string, integer]
description: The user must set up two-factor authentication at the next login
tls_enforce_in:
type: [string, integer]
tls_enforce_out:
type: [string, integer]
sogo_access:
type: [string, integer]
description: Login to SOGo from the UI
imap_access:
type: [string, integer]
pop3_access:
type: [string, integer]
smtp_access:
type: [string, integer]
sieve_access:
type: [string, integer]
eas_access:
type: [string, integer]
dav_access:
type: [string, integer]
relayhost:
type: [string, integer]
description: ID of the sender-dependent transport, "0" for none
shared:
type: [string, integer]
description: Shared mailbox without a login of its own
archive:
type: string
enum: [inherit, "1", "0"]
description: Archiving, `inherit` follows the domain
passwd_update:
type: [string, integer]
description: Time of the last password change
mailbox_format:
type: string
quarantine_notification:
type: string
enum:
- never
- hourly
- daily
- weekly
quarantine_category:
type: string
enum:
- reject
- add_header
- all
attribute_hash:
type: string
description: Hash of the template the settings came from, cleared by manual changes
recovery_email:
type: string
description: Address for password reset mails (present after it was set)
template:
type: string
description: Name of the template the mailbox was created from (if any)
Mailbox:
type: object
description: >-
A mailbox. The reduced form lacks `max_new_quota`, `spam_aliases`,
`pushover_active`, `rl`, `rl_scope`, `is_relayed` and `sender_acl`;
`tags` is missing without tags.
properties:
username:
type: string
description: Address of the mailbox
active:
type: integer
description: 1 active, 0 inactive, 2 login disabled (mail is still accepted)
active_int:
type: integer
description: Same as `active`
domain:
type: string
name:
type: string
description: Full name
local_part:
type: string
quota:
type: integer
description: Quota in bytes, 0 = unlimited
messages:
type: integer
description: Number of messages
attributes:
$ref: "#/components/schemas/MailboxAttributes"
custom_attributes:
type: [object, array]
description: Custom attributes (an empty list when there are none)
additionalProperties:
type: string
quota_used:
type: integer
description: Used bytes
percent_in_use:
type: [integer, string]
description: Used part of the quota in percent, "- " for unlimited quota
created:
type: string
modified:
type: [string, "null"]
authsource:
type: string
enum:
- mailcow
- keycloak
- generic-oidc
- ldap
percent_class:
type: string
enum:
- info
- success
- warning
- danger
description: info (unlimited), success, warning (≥ 75 %), danger (≥ 90 %)
last_imap_login:
type: integer
description: Unix time of the last IMAP login, 0 = none
last_smtp_login:
type: integer
last_pop3_login:
type: integer
last_sso_login:
type: integer
last_sogo_login:
type: integer
max_new_quota:
type: integer
description: Largest quota in bytes the mailbox may get (domain limits)
spam_aliases:
type: integer
description: Number of valid time-limited aliases
pushover_active:
type: integer
enum: [0, 1]
rl:
description: Effective rate limit, `false` if there is none
oneOf:
- $ref: "#/components/schemas/MailboxRatelimit"
- type: boolean
const: false
rl_scope:
type: string
enum:
- mailbox
- domain
description: Whether `rl` is the mailbox's own limit or the domain limit
is_relayed:
type: integer
description: 1 if the domain is relayed (backup MX)
sender_acl:
type: array
description: Internal addresses and @domains the mailbox may send as
items:
type: string
archive:
type: integer
enum: [0, 1]
description: Mails of the mailbox go to the archive now
tags:
type: array
items:
type: string
MailboxAdd:
type: object
required:
- local_part
- domain
properties:
local_part:
type: string
description: Part before the @
domain:
type: string
description: Domain of the mailbox
name:
type: string
description: Full name (`<` and `>` at the ends are removed)
authsource:
type: string
enum:
- mailcow
- keycloak
- generic-oidc
- ldap
default: mailcow
description: Login source; an external one only if it is the configured identity provider, else mailcow
password:
type: string
format: password
description: Checked against the password policy; empty (with `password2`) for a shared mailbox
password2:
type: string
format: password
description: The password again
template:
type: [integer, string]
description: ID of the mailbox template for the defaults (default the first)
quota:
type: [integer, string]
description: Quota in MiB, 0 = unlimited
active:
type: [integer, string]
enum: [0, 1, 2, "0", "1", "2"]
description: 1 active, 0 inactive, 2 login disabled (mail is accepted)
tags:
type: array
items:
type: string
description: Tags (the first 26 are saved)
protocol_access:
type: array
description: Allowed protocols; when sent it replaces the single `*_access` fields
items:
$ref: "#/components/schemas/ProtocolAccessName"
imap_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
pop3_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
smtp_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
sieve_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
eas_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
dav_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
sogo_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Login to SOGo from the UI
force_pw_update:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Password change at the first login (always 0 for external sources)
force_tfa:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Two-factor setup at the first login (always 0 for generic-oidc)
tls_enforce_in:
type: [integer, string]
enum: [0, 1, "0", "1"]
tls_enforce_out:
type: [integer, string]
enum: [0, 1, "0", "1"]
relayhost:
type: [integer, string]
default: 0
description: ID of a sender-dependent transport, 0 = none
shared:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Shared mailbox without a login of its own, opened by group members
archive:
type: string
enum: [inherit, "1", "0"]
description: >-
Archiving, `inherit` follows the domain (admins, domain admins with the
`archive` ACL)
quarantine_notification:
type: string
enum:
- never
- hourly
- daily
- weekly
quarantine_category:
type: string
enum:
- reject
- add_header
- all
tagged_mail_handler:
type: string
enum:
- subfolder
- subject
- none
description: Handling of mail to address+tag, see `edit/delimiter_action`
acl:
type: array
description: User ACLs to grant; when sent, all others are off
items:
$ref: "#/components/schemas/UserAclName"
rl_value:
type: [integer, string]
description: Rate limit, messages per `rl_frame` (0 or empty = none)
rl_frame:
type: string
enum:
- s
- m
- h
- d
attribute_hash:
type: string
description: Internal, the hash of the template the values come from
MailboxEdit:
type: object
properties:
active:
type: [integer, string]
enum: [0, 1, 2, "0", "1", "2"]
description: 1 active, 0 inactive, 2 login disabled (mail is accepted)
name:
type: string
description: Full name; empty keeps the current name
quota:
type: [integer, string]
description: Quota in MiB, 0 = unlimited; empty keeps the current quota
password:
type: string
format: password
description: New password (authsource mailcow), checked against the password policy
password2:
type: string
format: password
authsource:
type: string
enum:
- mailcow
- keycloak
- generic-oidc
- ldap
description: An external source only if it is the configured identity provider
pw_recovery_email:
type: string
description: Address for password reset mails (authsource mailcow only)
force_pw_update:
type: [integer, string]
enum: [0, 1, "0", "1"]
force_tfa:
type: [integer, string]
enum: [0, 1, "0", "1"]
sogo_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
protocol_access:
type: array
description: Allowed protocols; when sent it replaces the single `*_access` fields
items:
$ref: "#/components/schemas/ProtocolAccessName"
imap_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
pop3_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
smtp_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
sieve_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
eas_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
dav_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
relayhost:
type: [integer, string]
description: ID of a sender-dependent transport, 0 = none
shared:
type: [integer, string]
enum: [0, 1, "0", "1"]
archive:
type: string
enum: [inherit, "1", "0"]
description: >-
Archiving, `inherit` follows the domain (admins, domain admins with the
`archive` ACL)
tags:
type: array
items:
type: string
description: Tags to add; existing tags stay (remove with `delete/mailbox/tag/{mailbox}`)
tagged_mail_handler:
type: string
enum:
- subfolder
- subject
- none
sender_acl:
description: >-
Replaces the internal addresses and @domains the mailbox may send
as; `*` (admins only) allows all, `["default"]` removes all
oneOf:
- type: string
- type: array
items:
type: string
extended_sender_acl:
type: string
description: Replaces the external sender addresses or domains, separated by space, comma or semicolon
attribute_hash:
type: string
description: Internal; cleared when not sent
MailboxTemplateInput:
type: object
properties:
quota:
type: [integer, string]
default: 0
description: Quota in MiB, 0 = unlimited
tags:
type: array
items:
type: string
tagged_mail_handler:
type: string
enum:
- subfolder
- subject
- none
default: none
quarantine_notification:
type: string
enum:
- never
- hourly
- daily
- weekly
default: hourly
quarantine_category:
type: string
enum:
- reject
- add_header
- all
default: reject
rl_value:
type: [integer, string]
description: Rate limit, messages per `rl_frame`
rl_frame:
type: string
enum:
- s
- m
- h
- d
default: s
force_pw_update:
type: [integer, string]
enum: [0, 1, "0", "1"]
force_tfa:
type: [integer, string]
enum: [0, 1, "0", "1"]
sogo_access:
type: [integer, string]
enum: [0, 1, "0", "1"]
archive:
type: string
enum: [inherit, "1", "0"]
description: Archiving, `inherit` follows the domain
active:
type: [integer, string]
enum: [0, 1, 2, "0", "1", "2"]
default: 1
tls_enforce_in:
type: [integer, string]
enum: [0, 1, "0", "1"]
tls_enforce_out:
type: [integer, string]
enum: [0, 1, "0", "1"]
protocol_access:
type: array
items:
$ref: "#/components/schemas/ProtocolAccessName"
description: Allowed protocols (default all)
acl:
type: array
items:
$ref: "#/components/schemas/UserAclName"
description: User ACLs granted to new mailboxes
MailboxTemplate:
type: object
properties:
id:
type: integer
template:
type: string
description: Name
type:
type: string
const: mailbox
attributes:
type: object
description: The settings as in the example; quota in bytes, one `acl_<name>` flag per user ACL
additionalProperties: true
created:
type: string
modified:
type: [string, "null"]
Resource:
type: object
properties:
name:
type: string
description: Address of the resource
kind:
type: string
enum:
- location
- group
- thing
multiple_bookings:
type: integer
description: 0 always free, -1 unlimited but busy when booked, n ≥ 1 at most n bookings
description:
type: string
active:
type: integer
active_int:
type: integer
domain:
type: string
local_part:
type: string
AppPassword:
type: object
properties:
id:
type: integer
name:
type: string
mailbox:
type: string
domain:
type: string
password:
type: string
description: Hash of the app password
created:
type: string
modified:
type: [string, "null"]
imap_access:
type: integer
smtp_access:
type: integer
dav_access:
type: integer
eas_access:
type: integer
pop3_access:
type: integer
sieve_access:
type: integer
active:
type: integer
SieveFilter:
type: object
properties:
active:
type: integer
enum: [0, 1]
id:
type: integer
username:
type: string
description: Mailbox
filter_type:
type: string
enum:
- prefilter
- postfilter
script_data:
type: string
description: The Sieve script
script_desc:
type: string
TimeLimitedAlias:
type: object
properties:
address:
type: string
goto:
type: string
description: Mailbox the alias delivers to
description:
type: string
validity:
type: integer
description: Unix time of expiry (0 when made permanent by an edit)
created:
type: string
modified:
type: [string, "null"]
permanent:
type: integer
enum: [0, 1]
SpamPolicyEntry:
type: object
properties:
object:
type: string
description: Mailbox or domain the entry belongs to
value:
type: string
description: Sender address, domain or pattern
prefid:
type: integer
description: ID for `delete/mailbox-policy`
MailboxRatelimit:
type: object
properties:
value:
type: string
description: Number of messages
frame:
type: string
enum:
- s
- m
- h
- d
description: Per second, minute, hour or day
SpamScore:
type: object
properties:
score:
type: string
description: '"low,high": junk folder from low, rejected from high'
LastLogin:
type: object
properties:
ui:
description: Previous successful UI login, `false` if there is none, `[]` for domain admins
oneOf:
- type: object
properties:
remote:
type: string
description: IP address
time:
type: integer
description: Unix time
- type: boolean
const: false
- type: array
maxItems: 0
sasl:
type: array
items:
type: object
properties:
real_rip:
type: string
description: Client IP; private and internal addresses as "Web/EAS/Internal (address)"
datetime:
type: string
service:
type: string
description: e.g. imap, smtp, pop3, SOGO, SSO, MAILCOWUI
app_password:
type: integer
description: ID of the app password used, 0 = none
app_password_name:
type: [string, "null"]
location:
type: string
description: Country code of public addresses (if known)
MailboxSearchRequest:
type: object
description: DataTables server-side request
properties:
draw:
type: integer
description: Counter, returned unchanged
start:
type: integer
description: Offset of the first row; without it all rows are returned
length:
type: integer
description: Rows per page, -1 = all
search:
type: object
properties:
value:
type: string
description: Searched in all searchable columns (substring)
order:
type: array
items:
type: object
properties:
column:
type: integer
description: Column number (index in `columns`)
dir:
type: string
enum:
- asc
- desc
columns:
type: array
description: Column n of the table is `columns[n]`; needed to search or sort
items:
type: object
properties:
data:
type: [string, integer]
description: >-
Name of the column in the UI; for this column's
`search.value` only a column number works, other values
filter the address
searchable:
type: [boolean, string]
description: true or "true" includes the column in the search
orderable:
type: [boolean, string]
description: true or "true" allows sorting by the column
search:
type: object
properties:
value:
type: string
description: Filter for this column only (substring)
MailboxSearchResult:
type: object
properties:
draw:
type: integer
recordsTotal:
type: integer
recordsFiltered:
type: integer
data:
type: array
items:
$ref: "#/components/schemas/Mailbox"
Alias:
type: object
properties:
in_primary_domain:
type: string
description: Target domain if `domain` is an alias domain, else empty
id:
type: integer
domain:
type: string
description: Domain of the address, a domain or alias domain
public_comment:
type: [string, "null"]
description: Comment shown to the users
private_comment:
type: [string, "null"]
description: Comment for administrators
goto:
type: string
description: >-
Comma-separated destination addresses, or `null@localhost`
(discard), `spam@localhost` (learn as spam), `ham@localhost` (learn
as ham)
address:
type: string
description: Alias address, `@example.org` for a catch-all
is_catch_all:
type: integer
description: 1 = catch-all of the domain
internal:
type: integer
description: 1 = only reachable from its own domain and its alias domains
active:
type: integer
description: 1 = active, 0 = inactive
active_int:
type: integer
description: Same as `active`
sogo_visible:
type: integer
description: 1 = selectable sender in SOGo
sogo_visible_int:
type: integer
description: Same as `sogo_visible`
sender_allowed:
type: integer
description: 1 = the destination mailboxes may send as this alias
group_id:
type: [integer, "null"]
description: >-
Mailbox group whose distribution address this is; such aliases can
only be changed in the group
group_name:
type: [string, "null"]
description: Name of that mailbox group
created:
type: string
description: Creation time, `YYYY-MM-DD hh:mm:ss`
modified:
type: [string, "null"]
description: Time of the last change
BccMap:
type: object
properties:
id:
type: integer
local_dest:
type: string
description: Domain as `@example.org` or the address of a mailbox or alias
bcc_dest:
type: string
description: Address that gets the copies
active:
type: integer
description: 1 = active, 0 = inactive
type:
type: string
enum:
- sender
- rcpt
description: "`sender`: mail sent by `local_dest`; `rcpt`: mail sent to it"
created:
type: string
domain:
type: string
description: Domain of `local_dest`
modified:
type: [string, "null"]
RecipientMap:
type: object
properties:
id:
type: integer
recipient_map_old:
type: string
description: Original recipient, an address or `@domain`
recipient_map_new:
type: string
description: New recipient, an address or `@domain`
active:
type: integer
description: 1 = active, 0 = inactive
created:
type: string
modified:
type: [string, "null"]
TlsPolicyMap:
type: object
properties:
id:
type: integer
dest:
type: string
description: Destination
policy:
type: string
enum:
- none
- may
- encrypt
- dane
- dane-only
- fingerprint
- verify
- secure
parameters:
type: [string, "null"]
description: Space-separated `name=value` attributes, may be empty
active:
type: integer
description: 1 = active, 0 = inactive
created:
type: string
modified:
type: [string, "null"]
Relayhost:
type: object
description: A sender-dependent transport
properties:
id:
type: integer
description: The value domains and mailboxes use as `relayhost`
hostname:
type: string
description: Next hop
username:
type: string
description: SMTP user name, empty without authentication
password:
type: string
description: SMTP password in clear text
active:
type: integer
description: 1 = active, 0 = inactive
password_short:
type: string
description: First three characters of the password and `...`
used_by_domains:
type: string
description: Comma-separated domains that use the transport, may be empty
used_by_mailboxes:
type: string
description: Comma-separated mailboxes that use the transport, may be empty
Transport:
type: object
description: A transport map entry
properties:
id:
type: integer
is_mx_based:
type: integer
description: 1 = `destination` is a regular expression for MX names
destination:
type: string
nexthop:
type: string
username:
type: string
description: SMTP user name, empty without authentication
password:
type: string
description: SMTP password in clear text
active:
type: integer
description: 1 = active, 0 = inactive
password_short:
type: string
description: First three characters of the password and `...`
ForwardingHost:
type: object
properties:
host:
type: string
description: IP address or network
source:
type: string
description: What was added (host name, domain or the address itself)
keep_spam:
type: string
enum:
- "yes"
- "no"
description: "`yes` = the mail of the host is not scanned for spam"
RspamdSettingAttributes:
type: object
properties:
desc:
type: string
description: Short description
content:
type: string
description: Rule content in Rspamd settings syntax
active:
type: [boolean, integer, string]
description: 1 = the rule is handed to Rspamd
default: 0
required:
- desc
- content
RspamdSetting:
type: object
properties:
id:
type: integer
desc:
type: string
description: Short description
content:
type: string
description: Rule content in Rspamd settings syntax
active:
type: integer
enum:
- 0
- 1
RspamdRegexMap:
type: string
description: File name of a global Rspamd regex map
enum:
- global_mime_from_blacklist.map
- global_mime_from_whitelist.map
- global_smtp_from_blacklist.map
- global_smtp_from_whitelist.map
- global_rcpt_blacklist.map
- global_rcpt_whitelist.map
- fishy_tlds.map
- bad_words.map
- bad_words_de.map
- bad_languages.map
- bulk_header.map
- bad_header.map
- monitoring_nolog.map
Preset:
type: object
properties:
name:
type: string
description: File name of the preset without `.yml`
headline:
type: string
description: Title, translated
content:
type: string
description: Rspamd settings rule or Sieve script
GlobalFilters:
type: object
properties:
prefilter:
type: string
description: Sieve script that runs before the filters of the mailboxes
postfilter:
type: string
description: Sieve script that runs after the filters of the mailboxes
MailQueueItem:
type: object
description: One message of `postqueue -j`
properties:
queue_name:
type: string
description: Queue, e.g. `active`, `deferred`, `hold`, `incoming`
queue_id:
type: string
arrival_time:
type: integer
description: Unix time
message_size:
type: integer
description: Size in bytes
forced_expire:
type: boolean
sender:
type: string
recipients:
type: array
description: Recipient addresses, with the reason of the delay in brackets if there is one
items:
type: string
QuarantineItem:
type: object
properties:
id:
type: integer
qid:
type: string
description: Postfix queue ID of the message
subject:
type: string
virus_flag:
type: integer
description: Greater than 0 when Rspamd found a virus (`VIRUS_FOUND`)
score:
type: number
description: Rspamd score
rcpt:
type: string
description: Mailbox the item belongs to
sender:
type: string
action:
type: string
description: Rspamd action, e.g. `reject` or `add header`
created:
type: integer
description: Unix time
notified:
type: integer
description: 1 when the recipient got a notification
QuarantineItemDetails:
type: object
properties:
id:
type: integer
qid:
type: string
description: Postfix queue ID of the message
subject:
type: string
score:
type: number
description: Rspamd score
ip:
type: string
description: IP of the sending server
action:
type: string
description: Rspamd action
symbols:
type: string
description: Rspamd symbols as JSON text
fuzzy_hashes:
type: string
description: Fuzzy hashes as JSON text
sender:
type: string
rcpt:
type: string
description: Mailbox the item belongs to
msg:
type: string
description: The raw message
domain:
type: [string, "null"]
notified:
type: integer
description: 1 when the recipient got a notification
created:
type: string
description: Time of quarantining (`YYYY-MM-DD HH:MM:SS`)
user:
type: string
description: Authenticated sender, `unknown` if none
qhash:
type: string
description: Secret of the release and delete links in the notification mails
Fail2Ban:
type: object
properties:
ban_time:
type: integer
description: Ban time in seconds
ban_time_increment:
type: boolean
description: The ban time grows with every ban of a network
max_ban_time:
type: integer
description: Maximum ban time in seconds
netban_ipv4:
type: integer
description: IPv4 prefix length that is banned
netban_ipv6:
type: integer
description: IPv6 prefix length that is banned
max_attempts:
type: integer
description: Failed logins within `retry_window` that lead to a ban
retry_window:
type: integer
description: Window in seconds for `max_attempts`
banlist_id:
type: string
description: ID of the banlist URL `/f2b-banlist?id=<banlist_id>`
manage_external:
type: integer
description: 1 = netfilter sets no rules, the banlist is for an external firewall
regex:
type: object
description: Regex filters by number
additionalProperties:
type: string
whitelist:
type: string
description: Allowlisted networks and hosts, one per line
blacklist:
type: string
description: Denylisted networks, one per line
perm_bans:
type: array
description: Permanent bans (only present when there are any)
items:
type: object
properties:
network:
type: string
ip:
type: string
active_bans:
type: array
description: Active bans (only present when there are any)
items:
type: object
properties:
queued_for_unban:
type: integer
description: 1 when the ban is about to be lifted
network:
type: string
ip:
type: string
banned_until:
type: string
description: Remaining ban time, e.g. `00h 27m 08s`
Admin:
type: object
description: An administrator account
properties:
username:
type: string
tfa_active:
type: integer
enum: [0, 1]
description: 1 = two-factor authentication is active
tfa_active_int:
type: integer
enum: [0, 1]
description: Same as `tfa_active`
active:
type: integer
enum: [0, 1]
description: 1 = the account can log in
active_int:
type: integer
enum: [0, 1]
description: Same as `active`
created:
type: string
description: Creation time (`YYYY-MM-DD hh:mm:ss`)
attributes:
type: object
properties:
force_tfa:
type: string
enum: ["0", "1"]
description: "\"1\" = two-factor authentication must be set up at the next login"
force_pw_update:
type: string
enum: ["0", "1"]
description: "\"1\" = the password must be changed at the next login"
DomainAdmin:
type: object
description: A domain administrator account
properties:
username:
type: string
tfa_active:
type: integer
enum: [0, 1]
description: 1 = two-factor authentication is active
tfa_active_int:
type: integer
enum: [0, 1]
description: Same as `tfa_active`
active:
type: integer
enum: [0, 1]
description: 1 = the account can log in
active_int:
type: integer
enum: [0, 1]
description: Same as `active`
created:
type: string
description: Creation time (`YYYY-MM-DD hh:mm:ss`)
attributes:
type: object
properties:
force_tfa:
type: string
enum: ["0", "1"]
description: "\"1\" = two-factor authentication must be set up at the next login"
force_pw_update:
type: string
enum: ["0", "1"]
description: "\"1\" = the password must be changed at the next login"
selected_domains:
type: array
description: The domains the account administers
items:
type: string
unselected_domains:
description: All other domains, `""` if there are none
oneOf:
- type: array
items:
type: string
- type: string
const: ""
DomainAdminAcl:
type: string
description: >-
ACL of a domain administrator. New domain administrators get all except
`pushover`, `extend_sender_acl` (sender ACL with external addresses),
`unlimited_quota`, `alias_domains` and `domain_desc`.
enum:
- syncjobs
- quarantine
- login_as
- sogo_access
- app_passwds
- bcc_maps
- pushover
- filters
- ratelimit
- spam_policy
- extend_sender_acl
- unlimited_quota
- protocol_access
- smtp_ip_access
- alias_domains
- mailbox_relayhost
- domain_relayhost
- domain_desc
- alias_external_goto
- mailbox_groups
ApiKey:
type: object
description: An API key
properties:
id:
type: integer
description:
type: string
description: Free text; `API_KEY` or `API_KEY_READ_ONLY` for the service keys
access:
type: string
enum:
- ro
- rw
description: "`ro`: read-only (get routes only), `rw`: read/write"
api_key:
type: string
description: The key value, sent in the `X-API-Key` header
allow_from:
type: array
description: IP addresses and networks the key may be used from
items:
type: string
skip_ip_check:
type: integer
enum: [0, 1]
description: 1 = the key may be used from any address
service:
type: integer
enum: [0, 1]
description: 1 = service key from mailcow.conf, can only be changed there
active:
type: integer
enum: [0, 1]
created:
type: [string, "null"]
modified:
type: [string, "null"]
ApiKeyAttributes:
type: object
description: Attributes of an API key for add and edit
properties:
description:
type: string
description: Free text, at most 255 characters
default: ""
access:
type: string
enum:
- ro
- rw
description: "`ro`: read-only (get routes only), `rw`: read/write. Required for a new key."
allow_from:
description: >-
Allowed IP addresses and CIDR networks, as list or as string
separated by spaces, commas, semicolons or newlines. An edit
replaces the list.
oneOf:
- type: string
- type: array
items:
type: string
skip_ip_check:
type: [integer, string, boolean]
description: 1/true = allow the key from any address
default: 0
active:
type: [integer, string, boolean]
description: 1/true = active
default: 1
OAuth2Client:
type: object
description: An OAuth2 client of the mailcow OAuth2 server
properties:
id:
type: integer
description: ID used by the API
client_id:
type: string
description: OAuth2 client ID
client_secret:
type: string
description: OAuth2 client secret
redirect_uri:
type: string
description: Redirect (callback) URL
grant_types:
type: [string, "null"]
description: Not used
scope:
type: string
description: Always `profile`
user_id:
type: [string, "null"]
description: Not used
SyslogLogEntry:
type: object
description: A log line of a container
properties:
time:
type: string
description: Unix time
program:
type: string
description: Process that wrote the line
priority:
type: string
description: Syslog priority (`info`, `warning`, `err`, ...)
message:
type: string
AcmeLogEntry:
type: object
properties:
time:
type: string
description: Unix time
message:
type: string
ApiLogEntry:
type: object
properties:
time:
type: integer
description: Unix time
uri:
type: string
description: Request URI
method:
type: string
description: HTTP method
remote:
type: string
description: Client address
data:
type: string
description: Form data of the request (`attr`, `items`), secrets replaced by `*`
AutodiscoverLogEntry:
type: object
properties:
time:
type: integer
description: Unix time
ua:
type: string
description: User agent of the client
user:
type: string
description: Requested e-mail address
ip:
type: string
description: Client address
service:
type: string
description: Offered service (`activesync`, `imap`) or an error
CronLogEntry:
type: object
properties:
time:
type: integer
description: Unix time
priority:
type: string
task:
type: string
description: Name of the task
message:
type: string
NetfilterLogEntry:
type: object
properties:
time:
type: integer
description: Unix time
priority:
type: string
description: "`info`, `warn` or `crit` (bans)"
message:
type: string
RatelimitLogEntry:
type: object
properties:
time:
type: integer
description: Unix time
rcpt:
type: string
description: Recipients, comma separated
from:
type: string
description: Envelope sender
user:
type: string
description: Authenticated user
rl_info:
type: string
description: Rate limit that was hit, `name(hash)`
rl_name:
type: string
description: Name of the rate limit (mailbox or domain)
rl_hash:
type: string
description: Hash of the rate limit bucket (see `delete/rlhash`)
qid:
type: string
description: Postfix queue ID
ip:
type: string
description: Client address
message_id:
type: string
header_subject:
type: string
header_from:
type: string
RspamdHistoryEntry:
type: object
description: A message scanned by Rspamd (fields of Rspamd's history)
properties:
unix_time:
type: integer
time_real:
type: number
description: Scan time in seconds
score:
type: number
required_score:
type: number
action:
type: string
description: "`no action`, `greylist`, `add header`, `rewrite subject`, `soft reject` or `reject`"
thresholds:
type: object
additionalProperties:
type: number
ip:
type: string
user:
type: string
description: Authenticated user, `unknown` for incoming mail
sender_smtp:
type: string
sender_mime:
type: string
rcpt_smtp:
type: array
items:
type: string
rcpt_mime:
type: array
items:
type: string
subject:
type: string
message-id:
type: string
size:
type: integer
is_skipped:
type: boolean
symbols:
type: object
description: Matched symbols by name
additionalProperties:
type: object
properties:
name:
type: string
score:
type: number
metric_score:
type: number
description:
type: string
options:
type: array
items:
type: string
additionalProperties: true
RspamdStats:
type: object
description: Statistics of Rspamd's controller (`/stat`)
properties:
version:
type: string
config_id:
type: string
uptime:
type: integer
description: Seconds
read_only:
type: boolean
scanned:
type: integer
learned:
type: integer
actions:
type: object
description: Number of messages per action
additionalProperties:
type: integer
scan_times:
type: array
items:
type: [number, "null"]
spam_count:
type: integer
ham_count:
type: integer
connections:
type: integer
control_connections:
type: integer
total_learns:
type: integer
statfiles:
type: array
description: Bayes statistics
items:
type: object
fuzzy_hashes:
type: object
additionalProperties:
type: integer
additionalProperties: true
SaslLogEntry:
type: object
properties:
service:
type: string
description: "`imap`, `pop3`, `smtp`, `sieve`, `SSO` (SOGo), ..."
app_password:
type: integer
description: ID of the app password used, 0 = the mailbox password
username:
type: string
real_rip:
type: string
description: Client address
datetime:
type: string
description: Time of the last login (`YYYY-MM-DD hh:mm:ss`)
UiLogEntry:
type: object
properties:
id:
type: integer
task:
type: string
description: ID of the request
type:
type: string
description: "`success`, `danger`, `warning` or `info`"
msg:
type: string
description: The message (JSON)
call:
type: string
description: The call that produced it (JSON)
user:
type: string
description: Account (`API` for API keys)
role:
type: string
remote:
type: string
description: Client address
time:
type: integer
description: Unix time
WatchdogLogEntry:
type: object
properties:
time:
type: string
description: Unix time
service:
type: string
description: Checked service
lvl:
type: string
description: Health in percent
hpnow:
type: string
description: Current health points
hptotal:
type: string
description: Maximum health points
hpdiff:
type: string
description: Change since the last check
ContainerStatus:
type: object
properties:
type:
type: string
const: info
container:
type: string
description: Service name
state:
type: string
description: Docker state (`running`, `exited`, `restarting`, ...)
started_at:
type: string
description: Start time (RFC 3339)
image:
type: string
HostStats:
type: object
properties:
cpu:
type: object
properties:
cores:
type: integer
usage:
type: number
description: CPU usage in percent
memory:
type: object
properties:
total:
type: integer
description: Bytes
usage:
type: number
description: Memory usage in percent
swap:
type: array
description: Swap total, used, free (bytes), used percent, swapped in, swapped out (bytes)
items:
type: number
uptime:
type: number
description: Seconds since boot
system_time:
type: string
description: Host time (`DD.MM.YYYY hh:mm:ss`)
architecture:
type: string
PasswordPolicy:
type: object
description: Password policy; the values are strings, `false` if never saved
properties:
length:
type: [string, boolean]
description: Minimum length
chars:
type: [string, boolean]
description: "\"1\": at least one letter"
special_chars:
type: [string, boolean]
description: "\"1\": at least one character that is no letter or digit"
lowerupper:
type: [string, boolean]
description: "\"1\": lowercase and uppercase letters"
numbers:
type: [string, boolean]
description: "\"1\": at least one digit"
MailboxGroupAttributes:
type: object
description: >-
Attributes of a mailbox group. Flags take `1`, `true`, `on` or `yes`
for on, anything else is off. Lists take a JSON array or a string
separated by spaces, commas, semicolons or newlines; entries are
lowercased.
properties:
name:
type: string
description: 1-100 characters, unique in the domain
description:
type: string
description: Max. 255 characters
default: ""
address:
type: string
description: >-
Distribution address in the domain of the group, not used by a
mailbox or alias yet; empty = none. Wins over `local_part`.
local_part:
type: string
description: Local part of the address in the domain of the group; empty = no address
members:
type:
- array
- string
items:
type: string
description: Regular mailboxes; replaces the manual members the caller may access
add_members:
type:
- array
- string
items:
type: string
description: Mailboxes to add
remove_members:
type:
- array
- string
items:
type: string
description: Manual members to remove
send_as:
type:
- array
- string
items:
type: string
description: >-
Replaces the addresses the members may send as: mailbox or alias
addresses or `@domain`; for the group address use `sender_allowed`
sender_allowed:
type:
- boolean
- integer
- string
description: Members may send as the group address
default: 0
sogo_visible:
type:
- boolean
- integer
- string
description: Offer the group address as identity in SOGo (only with `sender_allowed`)
default: 0
internal:
type:
- boolean
- integer
- string
description: Only logged-in senders of the domain may write to the group address
default: 0
active:
type:
- boolean
- integer
- string
default: 1
imap_grants:
description: >-
Replaces the mailboxes the members may open as Shared/<mailbox>; the
caller needs access to every owner. `subscribe` subscribes the
folders for every member once, within 15 minutes. JSON text is
accepted too.
type:
- array
- string
items:
type: object
required:
- owner
properties:
owner:
type: string
description: Mailbox to share
rights:
type: string
description: >-
read = lookup, read, write-seen; write = also write,
write-deleted, insert, post, expunge, create; full = also delete
enum:
- read
- write
- full
default: read
subscribe:
type:
- boolean
- integer
- string
default: 0
sogo_grants:
description: >-
Replaces the SOGo folders shared with the members; the caller needs
access to every owner. Pending until the owner has opened SOGo once.
`subscribe` subscribes every member once. JSON text is accepted too.
type:
- array
- string
items:
type: object
required:
- owner
properties:
owner:
type: string
description: Mailbox whose folder is shared
type:
type: string
enum:
- Calendar
- Contacts
default: Calendar
folder:
type: string
description: SOGo folder id (`A-Za-z0-9._-`, max. 100 characters)
default: personal
access:
type: string
enum:
- read
- write
default: read
subscribe:
type:
- boolean
- integer
- string
default: 0
template_id:
type:
- integer
- string
- "null"
description: >-
Admins only: id of a mailbox template applied to the members;
null, empty or 0 = none
priority:
type:
- integer
- string
description: >-
Admins only: -1000000 to 1000000; of several groups with a
template the one with the highest priority wins
default: 0
idp_ref:
type: string
description: >-
Admins only: Identity Provider group id to sync the members from
(max. 255 characters); empty = none
MailboxGroup:
type: object
properties:
id:
type: integer
domain:
type: string
name:
type: string
description:
type: string
address:
type:
- string
- "null"
description: Distribution address, null = none
sender_allowed:
type: integer
enum:
- 0
- 1
sogo_visible:
type: integer
enum:
- 0
- 1
internal:
type: integer
enum:
- 0
- 1
template_id:
type:
- integer
- "null"
template:
type:
- string
- "null"
description: Name of the template
priority:
type: integer
idp_ref:
type:
- string
- "null"
description: Identity Provider group id, set = members are synced
members:
type: array
items:
type: object
properties:
username:
type: string
source:
type: string
description: manual = added in mailcow, idp = added by the identity sync
enum:
- manual
- idp
send_as:
type: array
description: Addresses and `@domain` entries the members may send as
items:
type: string
imap_grants:
type: array
items:
type: object
properties:
owner:
type: string
rights:
type: string
enum:
- read
- write
- full
subscribe:
type: integer
enum:
- 0
- 1
state:
type: string
description: failed = setting the ACL failed, retried later
enum:
- pending
- applied
- failed
last_error:
type:
- string
- "null"
sogo_grants:
type: array
items:
type: object
properties:
owner:
type: string
type:
type: string
enum:
- Calendar
- Contacts
folder:
type: string
access:
type: string
enum:
- read
- write
subscribe:
type: integer
enum:
- 0
- 1
state:
type: string
description: pending (`last_error` folder_missing) until the SOGo folder of the owner exists
enum:
- pending
- applied
- failed
last_error:
type:
- string
- "null"
active:
type: integer
enum:
- 0
- 1
created:
type:
- string
- "null"
modified:
type:
- string
- "null"
can_edit:
type: boolean
description: The caller may change the group (false for read-only API keys)
MailboxGroupMemberships:
type: object
properties:
groups:
type: array
items:
type: object
properties:
id:
type: integer
domain:
type: string
name:
type: string
address:
type:
- string
- "null"
sender_allowed:
type: integer
active:
type: integer
priority:
type: integer
template:
type:
- string
- "null"
source:
type: string
enum:
- manual
- idp
template:
type:
- string
- "null"
description: Effective group template of the mailbox
send_as:
type: array
description: Addresses the mailbox may send as through its active groups
items:
type: string
SyncJobAttributes:
type: object
description: >-
Attributes of a sync job. Flags are cast to integers: `1`, `"1"` and
`true` are on; `0`, `"0"`, `false` and the string `"true"` are off.
Flags not sent on add are off. `host1`, `port1`, `enc1` and `authmech1`
are ignored, the connection comes from `source_id`.
properties:
source_id:
type:
- integer
- string
description: >-
Id of an active sync source the caller may see
(`GET /api/v1/get/syncjob_source/all`)
user1:
type: string
description: Remote username at the source, max. 255 characters
password1:
type: string
format: password
description: >-
Remote password; required unless the source uses XOAUTH2 (ignored
then); empty on edit = keep
mins_interval:
type:
- integer
- string
description: Minutes between runs, 1-43800
subfolder2:
type: string
description: Folder in the local mailbox to sync into, empty = none
default: ""
exclude:
type: string
description: Regular expression of remote folders to skip
default: ""
maxage:
type:
- integer
- string
description: Only sync messages up to this age in days (1-32000), 0 = all
default: 0
maxbytespersecond:
type:
- integer
- string
description: >-
Bandwidth limit in bytes/s (1-125000000), 0 = unlimited; the global
limit of `edit/imapsync_settings` caps it
default: 0
timeout1:
type:
- integer
- string
description: Timeout of the remote connection in seconds (1-32000)
default: 600
timeout2:
type:
- integer
- string
description: Timeout of the local connection in seconds (1-32000)
default: 600
custom_params:
type: array
description: >-
Extra imapsync options allowed by `GET /api/v1/get/syncjob_options`;
replaces the stored list, empty or null = none. Max. 100 options,
values max. 1000 characters, each value is one argument.
items:
$ref: "#/components/schemas/SyncJobCustomParam"
delete2duplicates:
type:
- integer
- string
- boolean
description: Delete duplicates in the local mailbox (--delete2duplicates)
delete1:
type:
- integer
- string
- boolean
description: Delete messages at the source after they were synced (--delete1)
delete2:
type:
- integer
- string
- boolean
description: Delete local messages that are not at the source (--delete2)
automap:
type:
- integer
- string
- boolean
description: Map special folders like "Sent Items" to their local counterparts (--automap)
skipcrossduplicates:
type:
- integer
- string
- boolean
description: Skip duplicates across folders, first come first served (--skipcrossduplicates)
subscribeall:
type:
- integer
- string
- boolean
description: Subscribe all folders (--subscribeall)
dry:
type:
- integer
- string
- boolean
description: Dry run, change nothing (--dry)
active:
type:
- integer
- string
- boolean
description: The job runs; a new job without `active` is inactive
default: 0
SyncJobCustomParam:
type: object
required:
- o
properties:
o:
type: string
description: Option name, case-insensitive, leading dashes are removed
example: folder
v:
type: string
description: Value, empty for flags
default: ""
example: INBOX
SyncJob:
type: object
description: A sync job; the remote password is never returned.
properties:
id:
type: integer
user2:
type: string
description: Local mailbox
user1:
type: string
description: Remote username
source_id:
type: integer
subfolder2:
type: string
exclude:
type: string
maxage:
type: integer
mins_interval:
type: integer
maxbytespersecond:
type: string
description: Bytes/s as text, "0" = unlimited
timeout1:
type: integer
timeout2:
type: integer
custom_params:
type:
- string
- "null"
description: 'JSON text of the option list, e.g. `[{"o":"folder","v":"INBOX"}]`'
custom_params_legacy:
type:
- string
- "null"
description: Free-text options of jobs from before the allowlist, not used by the runner
delete2duplicates:
type: integer
delete1:
type: integer
delete2:
type: integer
automap:
type: integer
skipcrossduplicates:
type: integer
subscribeall:
type: integer
dry:
type: integer
active:
type: integer
regextrans2:
type:
- string
- "null"
description: Legacy column, read-only
authmd51:
type: integer
description: Legacy column, read-only
domain2:
type: string
description: Legacy column, read-only
is_running:
type: integer
last_run:
type:
- string
- "null"
success:
type:
- integer
- "null"
description: Result of the last run (1 = imapsync exited with 0), null = not run yet
exit_status:
type:
- string
- "null"
description: Exit status name of imapsync, e.g. EX_OK
prio:
type: integer
description: Queue priority, higher runs first
created:
type:
- string
- "null"
modified:
type:
- string
- "null"
source_name:
type:
- string
- "null"
source_description:
type:
- string
- "null"
source_host:
type:
- string
- "null"
source_port:
type:
- integer
- "null"
source_enc:
type:
- string
- "null"
source_auth_type:
type:
- string
- "null"
source_created_by:
type:
- string
- "null"
source_scope:
type:
- string
- "null"
source_oauth_flow:
type:
- string
- "null"
source_active:
type:
- integer
- "null"
source_oauth_token_expires:
type:
- integer
- "null"
description: Expiry (Unix time) of the token of a client_credentials source
source_oauth_last_refresh_error:
type:
- string
- "null"
user_token_expires:
type:
- integer
- "null"
description: Expiry (Unix time) of the sign-in token of an authorization_code source
user_token_error:
type:
- string
- "null"
user_token_exists:
type: integer
description: 1 = a sign-in token exists for (source, local mailbox, user1)
log:
type: string
description: Output of the last run; empty with `no_log`
SyncJobSourceAttributes:
type: object
description: >-
Attributes of a sync source; on edit, attributes that are not sent keep
their value.
properties:
name:
type: string
description: 1-100 characters, unique per creator
description:
type: string
description: Max. 255 characters
default: ""
host:
type: string
description: IMAP server, host name or IP address (`host1` is accepted too)
port:
type:
- integer
- string
description: 1-65535 (`port1` is accepted too)
enc:
type: string
description: TLS = STARTTLS (`enc1` is accepted too)
enum:
- TLS
- SSL
- PLAIN
default: TLS
verify_cert:
type:
- integer
- string
- boolean
description: Verify the server certificate; `0`, `"0"`, `false` or empty = no
default: 1
auth_type:
type: string
description: >-
PLAIN, LOGIN and CRAM-MD5 use the password of each job, XOAUTH2 an
OAuth2 token. Users cannot create or edit XOAUTH2 sources, but may
use the ones they see.
enum:
- PLAIN
- LOGIN
- CRAM-MD5
- XOAUTH2
default: PLAIN
active:
type:
- integer
- string
description: 1 = usable for jobs (cast to integer)
default: 1
scope:
type: string
description: >-
Who may use the source: `all` (admins only), `domain` (the
`domains`), `user` (the `users`; none = only the creator). Sources
of users and client_credentials sources are always `user` without
targets. On edit the targets only change when `scope` is sent.
enum:
- all
- domain
- user
default: user
domains:
type: array
description: Domains for scope `domain` (at least one), the caller must manage them
items:
type: string
users:
type: array
description: Mailboxes for scope `user`, the caller must have access to them
items:
type: string
oauth_flow:
type: string
description: >-
XOAUTH2 grant: client_credentials = one token of the source for all
mailboxes of the tenant; authorization_code = every mailbox owner
signs in once in the mailcow UI (redirect URI
`https://<MAILCOW_HOSTNAME>/syncjob-oauth`)
enum:
- client_credentials
- authorization_code
default: client_credentials
oauth_token_endpoint:
type: string
description: XOAUTH2, required; https:// URL
oauth_authorize_endpoint:
type: string
description: XOAUTH2 authorization_code, required; https:// URL
oauth_userinfo_endpoint:
type: string
description: >-
XOAUTH2 authorization_code, optional: identity endpoint used when
the token response has no usable id_token; https:// URL
oauth_client_id:
type: string
description: XOAUTH2, required, max. 500 characters
oauth_client_secret:
type: string
format: password
description: >-
XOAUTH2, required, max. 500 characters; empty on edit = keep. Never
returned.
oauth_scope:
type: string
description: XOAUTH2, required, max. 500 characters
oauth_extra_params:
description: >-
XOAUTH2, optional: extra OAuth2 parameters as JSON object or JSON
text (max. 4000 characters). `prompt`, `access_type`, `login_hint`,
`domain_hint` and `hd` go to the sign-in URL, others to the token
request; standard fields cannot be overridden.
type:
- object
- string
- "null"
additionalProperties:
type:
- string
- number
- boolean
- "null"
SyncJobSource:
type: object
description: A sync source; secrets are never returned.
properties:
id:
type: integer
name:
type: string
description:
type: string
created_by:
type: string
description: Creator; `API` for API keys, empty = handed over to the admins (creator deleted)
scope:
type: string
enum:
- all
- domain
- user
domains:
type: array
items:
type: string
users:
type: array
items:
type: string
host:
type: string
port:
type: integer
enc:
type:
- string
- "null"
host1:
type: string
description: Same as `host`
port1:
type: integer
description: Same as `port`
enc1:
type:
- string
- "null"
description: Same as `enc`
verify_cert:
type: integer
auth_type:
type:
- string
- "null"
active:
type: integer
oauth_flow:
type: string
oauth_token_endpoint:
type:
- string
- "null"
oauth_authorize_endpoint:
type:
- string
- "null"
oauth_userinfo_endpoint:
type:
- string
- "null"
oauth_client_id:
type:
- string
- "null"
oauth_scope:
type:
- string
- "null"
oauth_extra_params:
type:
- string
- "null"
description: JSON text, null for callers who may not edit the source
oauth_token_expires:
type:
- integer
- "null"
description: Expiry (Unix time) of the token of a client_credentials source
oauth_last_refresh_error:
type:
- string
- "null"
oauth_last_refresh_attempt:
type:
- string
- "null"
oauth_redirect_uri:
type: string
description: Only for authorization_code sources, register it at the provider
has_client_secret:
type: boolean
has_access_token:
type: boolean
can_edit:
type: boolean
description: The caller may change the source (false for read-only API keys)
created:
type:
- string
- "null"
modified:
type:
- string
- "null"
SyncJobSettings:
type: object
properties:
max_parallel:
type: integer
description: Sync jobs running at the same time
max_bytes_per_second:
type: integer
description: Bandwidth limit per sync job process in bytes/s, 0 = unlimited
max_kb_per_second:
type: integer
description: The same in KB/s
IdentityProviderAttributes:
type: object
required:
- authsource
description: >-
Configuration of the Identity Provider. Flags marked (boolean) are on
for any non-empty value except `0`/`"0"`/`false`; flags marked (0/1) are
cast to integers (the string `"true"` is 0).
properties:
authsource:
type: string
description: Provider type (case-insensitive)
enum:
- keycloak
- generic-oidc
- ldap
client_id:
type: string
description: Keycloak, generic-oidc
client_secret:
type: string
format: password
description: Keycloak, generic-oidc
redirect_url:
type: string
description: Keycloak, generic-oidc; URL of mailcow the provider redirects to after the login
redirect_url_extra:
type:
- array
- string
items:
type: string
description: Keycloak, generic-oidc; more allowed redirect URLs, only changed when sent
server_url:
type: string
description: Keycloak base URL
realm:
type: string
description: Keycloak realm
version:
type: string
description: Keycloak version
mailpassword_flow:
type:
- integer
- string
- boolean
description: (0/1) Keycloak; check mail client passwords through the Keycloak admin API
default: 0
group_paths:
type: string
description: >-
Keycloak group sync: comma-separated group paths, e.g. `/Sales` or
`/mailcow/*` (all groups below /mailcow); needs the `query-groups`
permission
default: ""
authorize_url:
type: string
description: generic-oidc authorization endpoint
token_url:
type: string
description: generic-oidc token endpoint
userinfo_url:
type: string
description: generic-oidc userinfo endpoint
client_scopes:
type: string
description: generic-oidc scopes
default: openid profile email mailcow_template
host:
type: string
description: LDAP server, several separated by commas (spaces are removed)
default: ""
port:
type:
- integer
- string
description: LDAP port
default: 389
use_ssl:
type:
- boolean
- integer
- string
description: (boolean) LDAP over SSL
default: false
use_tls:
type:
- boolean
- integer
- string
description: (boolean) LDAP StartTLS, ignored with `use_ssl`
default: false
basedn:
type: string
description: LDAP base DN of the user search
binddn:
type: string
description: LDAP bind DN
bindpass:
type: string
format: password
description: LDAP bind password
username_field:
type: string
description: LDAP attribute with the mail address of the user
default: mail
filter:
type: string
description: LDAP filter of the users that may log in
default: ""
attribute_field:
type: string
description: LDAP attribute whose value is matched against `mappers`
default: ""
id_attribute:
type: string
description: >-
LDAP attribute with a stable user id; empty = objectGUID, entryUUID,
nsUniqueId or ipaUniqueID, else the DN
default: ""
disabled_filter:
type: string
description: >-
LDAP filter of disabled users (Active Directory accounts with
ACCOUNTDISABLE are always disabled)
default: ""
group_basedn:
type: string
description: LDAP base DN of the group search, empty = `basedn`
default: ""
group_filter:
type: string
description: LDAP filter of the synced groups, required for the group sync
default: ""
group_name_attribute:
type: string
default: cn
group_member_mode:
type: string
description: >-
LDAP source of the memberships: memberOf of the users, member
attribute of the groups, or Active Directory incl. nested groups
enum:
- memberof
- member
- ad_chain
default: memberof
group_member_attribute:
type: string
description: LDAP member attribute for `group_member_mode` member
default: member
ignore_ssl_error:
type:
- boolean
- integer
- string
description: (boolean) Do not verify TLS certificates
default: false
login_provisioning:
type:
- boolean
- integer
- string
description: (boolean) Create mailboxes at their first login
default: false
periodic_sync:
type:
- integer
- string
- boolean
description: (0/1) Keycloak, LDAP; update mailboxes from the provider every `sync_interval`
default: 0
import_users:
type:
- integer
- string
- boolean
description: (0/1) Keycloak, LDAP; create mailboxes for new users of the provider
default: 0
sync_interval:
type:
- integer
- string
description: Keycloak, LDAP; minutes between sync runs (at least 1)
default: 15
offboarding:
type:
- integer
- string
- boolean
description: >-
(0/1) Keycloak, LDAP; disable the login (mail still arrives) of users
disabled at the provider or missing in two complete runs; the sync
enables only mailboxes it disabled
default: 0
offboarding_limit:
type:
- integer
- string
description: >-
Keycloak, LDAP; runs that would disable more mailboxes or remove
more group memberships than this share in percent (0-100, at least
5 mailboxes) are blocked
default: 10
group_sync:
type:
- integer
- string
- boolean
description: >-
(0/1) Keycloak, LDAP; sync the members of provider groups to mailbox
groups (members added in mailcow stay)
default: 0
group_autocreate:
type:
- integer
- string
- boolean
description: >-
(0/1) Keycloak, LDAP; create a mailbox group for every provider
group without one
default: 0
group_default_domain:
type: string
description: Keycloak, LDAP; domain of new groups whose mail is not in a mailcow domain
default: ""
default_template:
type: string
description: >-
Mailbox template for new mailboxes without a matching mapping (not
used for updates); only changed when sent
mappers:
type: array
items:
type: string
description: >-
Attribute values, each mapped to the template at the same position
in `templates`; only changed when both lists are sent, pairs with an
empty value are dropped
templates:
type: array
items:
type: string
description: Mailbox templates for `mappers`
IdentityProviderSettings:
type: object
description: >-
Stored settings (see `IdentityProviderAttributes`), mostly as strings.
Secrets are `*` for read-only API keys.
properties:
authsource:
type: string
client_secret:
type: string
bindpass:
type: string
access_token:
type: string
description: Cached admin API token of Keycloak
redirect_url_extra:
type: array
items:
type: string
mappers:
type: array
items:
type: string
templates:
type: array
items:
type: string
use_ssl:
type: boolean
use_tls:
type: boolean
ignore_ssl_error:
type: boolean
login_provisioning:
type:
- boolean
- integer
additionalProperties:
type: string
IdentitySyncStatus:
type: object
properties:
provider:
type: string
description: Configured provider, empty = none
can_sync:
type: boolean
description: The provider can be synced (Keycloak, LDAP)
sync_enabled:
type: boolean
description: Scheduled runs are on (periodic sync, import, offboarding or group sync)
counts:
type: object
description: Mailboxes of the provider (no resources)
properties:
accounts:
type: integer
linked:
type: integer
description: Linked to a user of the provider
idp_disabled:
type: integer
description: Login disabled by the sync
missing:
type: integer
description: Not found at the provider by the last runs
runs:
type: array
description: The last 10 runs, newest first
items:
$ref: "#/components/schemas/IdentitySyncRun"
IdentitySyncRun:
type: object
properties:
id:
type: integer
provider:
type: string
mode:
type: string
enum:
- run
- preview
- force
status:
type: string
enum:
- pending
- running
- ok
- blocked
- error
requested_by:
type: string
description: Who requested the run, empty for scheduled runs
created:
type: string
started:
type:
- string
- "null"
finished:
type:
- string
- "null"
summary:
type:
- object
- "null"
description: >-
Result, null while pending: `counts` per kind of change, `details`
(up to 50 entries per list), `blocked`, `errors` (up to 50), `mode`;
failed runs only `error` and `mode`
properties:
counts:
type: object
additionalProperties:
type: integer
details:
type: object
additionalProperties:
type: array
items:
type: string
blocked:
type: boolean
errors:
type: array
items:
type: string
error:
type: string
mode:
type: string
IdentityLink:
type: object
properties:
provider:
type: string
external_id:
type:
- string
- "null"
description: User id at the provider
idp_disabled:
type: integer
description: 1 = login disabled by the identity sync
missing_since:
type:
- string
- "null"
description: Since when the sync does not find the user at the provider
responses:
Unauthorized:
description: >-
The API key is unknown or inactive (`authentication failed`), or the
request comes from an address the key does not allow
(`api access denied for ip <address>`)
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
type: error
msg: authentication failed
Forbidden:
description: The API key is read-only
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
type: error
msg: API read/write access denied
WriteResult:
description: >-
The messages of the call; `{"type": "success", "msg": "Task completed"}`
or `{"type": "error", "msg": "Cannot ... item"}` if it produced none.
Check `type`: the status is 200 for failures too.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Messages"
- $ref: "#/components/schemas/TaskResult"
examples:
messages:
summary: Messages of the call
value:
- type: success
log:
- mailbox
- add
- alias
- address: alias@example.org
goto: user@example.org
msg:
- alias_added
- alias@example.org
failed:
summary: Failed without a message
value:
type: error
msg: Cannot add item
AcmeLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AcmeLogEntry"
example:
- time: "1794308452"
message: mail.example.org - Certificates were successfully validated, no changes or renewals required, sleeping for another day.
ApiLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ApiLogEntry"
example:
- time: 1794334338
uri: /api/v1/edit/domain-admin
method: POST
remote: 192.0.2.10
data: "attr='{\"active\":\"1\",\"password\":\"*\",\"password2\":\"*\"}', items='[\"domainadmin1\"]'"
- time: 1794334330
uri: /api/v1/get/status/version
method: GET
remote: 192.0.2.10
data: ""
AutodiscoverLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AutodiscoverLogEntry"
example:
- time: 1794311051
ua: Microsoft Office/16.0 (Windows NT 10.0; Microsoft Outlook 16.0.17928; Pro)
user: john.doe@example.org
ip: 198.51.100.7
service: activesync
CronLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/CronLogEntry"
example:
- time: 1794096901
priority: warning
task: Group Shares
message: "group_imap_grant_failed: info@example.org"
DovecotLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyslogLogEntry"
example:
- time: "1794334332"
program: dovecot
priority: info
message: "imap-login: Login: user=<john.doe@example.org>, method=PLAIN, rip=198.51.100.7, lip=172.22.1.250, mpid=310, TLS, session=<c0kD4l8L2N7GZGMH>"
NetfilterLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/NetfilterLogEntry"
example:
- time: 1794334242
priority: crit
message: Banning 203.0.113.5/32 for 30 minutes
- time: 1794334242
priority: warn
message: "203.0.113.5 matched rule id 3 (warning: unknown[203.0.113.5]: SASL LOGIN authentication failed: ...)"
PostfixLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyslogLogEntry"
example:
- time: "1794334301"
program: postfix/smtpd
priority: info
message: "connect from mail.example.com[198.51.100.20]"
RatelimitLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/RatelimitLogEntry"
example:
- time: 1794334001
rcpt: jane@example.com
from: john.doe@example.org
user: john.doe@example.org
rl_info: john.doe@example.org(RLsdz3tuabozgd4oacbdh8kc78)
rl_name: john.doe@example.org
rl_hash: RLsdz3tuabozgd4oacbdh8kc78
qid: E3CF91500458
ip: 172.22.1.248
message_id: 6a-5d892500-7-240abd80@example.org
header_subject: Newsletter
header_from: "\"John Doe\" <john.doe@example.org>"
RspamdHistory:
description: The scanned messages, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/RspamdHistoryEntry"
example:
- unix_time: 1794333685
time_real: 0.510136
score: -1.229459
required_score: 15
action: no action
thresholds:
reject: 15
add header: 8
greylist: 7
ip: 198.51.100.20
user: unknown
sender_smtp: jane@example.com
sender_mime: jane@example.com
rcpt_smtp:
- john.doe@example.org
rcpt_mime:
- john.doe@example.org
subject: Meeting tomorrow
message-id: 20261110190100.428319@mail.example.com
size: 1015
is_skipped: false
symbols:
DMARC_POLICY_ALLOW:
name: DMARC_POLICY_ALLOW
score: -0.5
metric_score: -0.5
description: DMARC permit policy
options:
- example.com
- none
SaslLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SaslLogEntry"
example:
- service: imap
app_password: 0
username: john.doe@example.org
real_rip: 198.51.100.7
datetime: "2026-11-10 19:07:01"
SogoLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyslogLogEntry"
example:
- time: "1794334303"
program: sogod
priority: notice
message: "[52]: 198.51.100.7 \"GET /SOGo/so/john.doe@example.org/Mail/view HTTP/1.1\" 200 2578/0 0.002 - - 0 - 12"
UiLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/UiLogEntry"
example:
- id: 1819
task: 97D254
type: success
msg: "[\"domain_admin_modified\",\"domainadmin1\"]"
call: "[\"domain_admin\",\"edit\",{\"username\":[\"domainadmin1\"],\"active\":\"1\"}]"
user: API
role: admin
remote: 192.0.2.10
time: 1794319670
WatchdogLogs:
description: The log entries, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/WatchdogLogEntry"
example:
- time: "1794334334"
service: Dovecot
lvl: "100"
hpnow: "12"
hptotal: "12"
hpdiff: "0"
parameters:
MailboxTagsQuery:
name: tags
in: query
required: false
description: "Comma-separated tags: only mailboxes with a tag containing one of them"
schema:
type: string
example: sales,support
examples:
MailboxDetails:
summary: A mailbox
value:
username: john.doe@example.org
active: 1
active_int: 1
domain: example.org
name: John Doe
local_part: john.doe
quota: 3221225472
messages: 1207
attributes:
force_pw_update: "0"
force_tfa: "0"
tls_enforce_in: "0"
tls_enforce_out: "0"
sogo_access: "1"
imap_access: "1"
pop3_access: "0"
smtp_access: "1"
sieve_access: "1"
eas_access: "1"
dav_access: "1"
relayhost: "0"
shared: "0"
passwd_update: "2026-11-03 09:37:37"
mailbox_format: "maildir:"
quarantine_notification: hourly
quarantine_category: reject
attribute_hash: ""
recovery_email: ""
custom_attributes:
department: Sales
quota_used: 418219315
percent_in_use: 13
created: "2026-11-03 09:37:37"
modified: "2026-11-06 20:20:46"
authsource: mailcow
percent_class: success
last_imap_login: 1794052021
last_smtp_login: 1793788402
last_pop3_login: 0
last_sso_login: 1794005152
last_sogo_login: 1794005160
max_new_quota: 10737418240
spam_aliases: 1
pushover_active: 0
rl:
value: "100"
frame: h
rl_scope: mailbox
is_relayed: 0
sender_acl:
- sales@example.org
tags:
- sales
MailboxList:
summary: Mailboxes
value:
- username: john.doe@example.org
active: 1
active_int: 1
domain: example.org
name: John Doe
local_part: john.doe
quota: 3221225472
messages: 1207
attributes:
force_pw_update: "0"
force_tfa: "0"
tls_enforce_in: "0"
tls_enforce_out: "0"
sogo_access: "1"
imap_access: "1"
pop3_access: "0"
smtp_access: "1"
sieve_access: "1"
eas_access: "1"
dav_access: "1"
relayhost: "0"
shared: "0"
passwd_update: "2026-11-03 09:37:37"
mailbox_format: "maildir:"
quarantine_notification: hourly
quarantine_category: reject
attribute_hash: ""
custom_attributes: []
quota_used: 418219315
percent_in_use: 13
created: "2026-11-03 09:37:37"
modified: "2026-11-06 20:20:46"
authsource: mailcow
percent_class: success
last_imap_login: 1794052021
last_smtp_login: 1793788402
last_pop3_login: 0
last_sso_login: 0
last_sogo_login: 1794005160
max_new_quota: 10737418240
spam_aliases: 0
pushover_active: 0
rl: false
rl_scope: domain
is_relayed: 0
sender_acl: []
MailboxSearchPage:
summary: One page of mailboxes
value:
draw: 1
recordsTotal: 1
recordsFiltered: 1
data:
- username: john.doe@example.org
active: 1
active_int: 1
domain: example.org
name: John Doe
local_part: john.doe
quota: 3221225472
messages: 1207
attributes:
force_pw_update: "0"
force_tfa: "0"
tls_enforce_in: "0"
tls_enforce_out: "0"
sogo_access: "1"
imap_access: "1"
pop3_access: "0"
smtp_access: "1"
sieve_access: "1"
eas_access: "1"
dav_access: "1"
relayhost: "0"
shared: "0"
passwd_update: "2026-11-03 09:37:37"
mailbox_format: "maildir:"
quarantine_notification: hourly
quarantine_category: reject
attribute_hash: ""
custom_attributes: []
quota_used: 418219315
percent_in_use: 13
created: "2026-11-03 09:37:37"
modified: "2026-11-06 20:20:46"
authsource: mailcow
percent_class: success
last_imap_login: 1794052021
last_smtp_login: 1793788402
last_pop3_login: 0
last_sso_login: 0
last_sogo_login: 1794005160
max_new_quota: 10737418240
spam_aliases: 0
pushover_active: 0
rl: false
rl_scope: domain
is_relayed: 0
sender_acl: []
tags:
- sales
security:
- ApiKeyAuth: []
paths:
/api/v1/add/alias:
post:
tags:
- Aliases
summary: Create aliases
operationId: addAlias
description: >-
Creates an alias for every address in `address`, all with the same
destinations; domain administrators for their domains. Flags not sent
are 0: send `active`, `sogo_visible` and `sender_allowed` as 1 to get
an alias like the UI creates it.
Messages: `alias_added`; errors `is_alias_or_mailbox`, `goto_invalid`,
`external_goto_denied`, `max_alias_exceeded`.
requestBody:
content:
application/json:
schema:
type: object
properties:
address:
type: string
description: >-
Alias addresses of mailcow domains or alias domains,
separated by spaces, commas, semicolons or line breaks;
`@example.org` is a catch-all
goto:
type: string
description: >-
Destination addresses, separated by spaces, commas,
semicolons or line breaks; required unless a `goto_*` flag
is 1
goto_null:
type: [boolean, integer, string]
description: 1 = discard the mail silently; wins over `goto_spam` and `goto_ham`
default: 0
goto_spam:
type: [boolean, integer, string]
description: 1 = learn the mail as spam; wins over `goto_ham`
default: 0
goto_ham:
type: [boolean, integer, string]
description: 1 = learn the mail as ham
default: 0
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
default: 0
sogo_visible:
type: [boolean, integer, string]
description: 1 = selectable sender in SOGo (aliases with a local mailbox as destination)
default: 0
internal:
type: [boolean, integer, string]
description: 1 = only reachable from its own domain and its alias domains
default: 0
sender_allowed:
type: [boolean, integer, string]
description: 1 = the destination mailboxes may send as this alias
default: 0
public_comment:
type: string
description: Comment shown to the users
maxLength: 160
private_comment:
type: string
description: Comment for administrators
maxLength: 160
required:
- address
example:
address: sales@example.org
goto: anna@example.org,ben@example.org
active: "1"
sogo_visible: "1"
sender_allowed: "1"
internal: "0"
public_comment: Sales team
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/time_limited_alias:
post:
tags:
- Mailbox user settings
summary: Create a time-limited alias
operationId: addTimeLimitedAlias
description: >-
Creates a random alias that delivers to the mailbox until it expires.
Needs the user ACL `spam_alias`. `domain` must be the domain of the
mailbox or one of its alias domains.
Messages: `mailbox_modified`; errors `domain_invalid`,
`validity_missing`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
username:
type: string
description: Mailbox the alias delivers to (required for API keys)
domain:
type: string
description: Domain of the alias
description:
type: string
default: ""
description: Note for the alias
validity:
type: [integer, string]
minimum: 1
maximum: 87600
default: 8760
description: Hours until the alias expires
permanent:
type: [boolean, integer, string]
default: false
description: true keeps the alias after it expired
example:
username: john.doe@example.org
domain: example.org
description: Online shop registration
validity: 720
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/api-key:
post:
summary: Create API key
description: >-
Creates an API key with a random value; read the value with
`get/api-key/all`. Without `skip_ip_check`, `allow_from` is required.
Messages: `api_key_added`; errors `api_key_access_invalid`,
`api_key_network_invalid`, `ip_list_empty`.
operationId: addApiKey
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiKeyAttributes"
- required:
- access
example:
description: provisioning
access: rw
allow_from: "192.0.2.10, 2001:db8::/64"
skip_ip_check: 0
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/app-passwd:
post:
tags:
- App Passwords
summary: Create an app password
operationId: addAppPassword
description: >-
Adds an app password to a mailbox, valid only for the listed protocols.
Needs the user ACL `app_passwds`.
Messages: `app_passwd_added`; errors `password_complexity`,
`password_mismatch`, `app_name_empty`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- app_name
- app_passwd
- app_passwd2
properties:
username:
type: string
description: Mailbox the app password belongs to (required for API keys)
app_name:
type: string
description: Name of the app password
app_passwd:
type: string
format: password
description: The password, checked against the password policy
app_passwd2:
type: string
format: password
description: The password again
protocols:
description: Protocols the password is valid for; not listed = not allowed
type: array
items:
type: string
enum:
- imap_access
- smtp_access
- pop3_access
- sieve_access
- dav_access
- eas_access
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: 1 active, 0 inactive
example:
username: john.doe@example.org
app_name: Thunderbird
app_passwd: eiQu4ahz8iePh
app_passwd2: eiQu4ahz8iePh
protocols:
- imap_access
- smtp_access
- sieve_access
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/bcc:
post:
tags:
- Address Rewriting
summary: Create a BCC map
operationId: addBccMap
description: >-
Sends a hidden copy of the mail of a domain or address to `bcc_dest`.
Domain administrators need the BCC maps ACL. Undeliverable copies are
not reported to the local destination.
Messages: `bcc_saved`; errors `bcc_must_be_email`, `bcc_exists`.
requestBody:
content:
application/json:
schema:
type: object
properties:
local_dest:
type: string
description: A mailcow domain or the address of a mailbox or alias
bcc_dest:
type: string
description: One e-mail address that gets the copies (use an alias for several)
type:
type: string
enum:
- sender
- rcpt
description: >-
`sender`: copy the mail sent by `local_dest`; `rcpt`: copy
the mail sent to it
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
default: 0
required:
- local_dest
- bcc_dest
- type
example:
local_dest: example.org
bcc_dest: archive@example.com
type: rcpt
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/dkim:
post:
summary: Generate DKIM keys
description: >-
Generates an RSA DKIM key for each domain or alias domain; existing
keys are kept.
Messages: `dkim_added`; error `dkim_domain_or_sel_invalid`.
operationId: addDkimKey
tags:
- DKIM
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
- key_size
properties:
domains:
type: string
description: >-
Domain names, separated by spaces, commas, semicolons or
line breaks
dkim_selector:
type: string
default: dkim
description: Selector (letters, digits, `-`, `_`, `.`)
key_size:
type: [integer, string]
description: RSA key size in bits
example:
domains: example.org, example.net
dkim_selector: dkim
key_size: 2048
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/dkim_duplicate:
post:
summary: Copy a DKIM key to other domains
description: >-
Copies the DKIM key and selector of `from_domain` to the `to_domain`
domains, replacing their keys. Target names are not checked.
Messages: `dkim_duplicated`; error `dkim_domain_or_sel_invalid`.
operationId: duplicateDkimKey
tags:
- DKIM
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from_domain
- to_domain
properties:
from_domain:
type: string
description: Domain whose key is copied
to_domain:
description: Domain name or list of domain names that get the key
oneOf:
- type: string
- type: array
items:
type: string
example:
from_domain: example.org
to_domain:
- example.net
- example.com
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/domain:
post:
summary: Add a domain
description: >-
Adds a domain. Quotas are in MiB. Fields not sent come from the domain
template in `template` (default: `Default`). Also sets the rate limit
and creates a DKIM key. SOGo sees the new domain only after a restart
(`restart_sogo`).
Messages: `domain_added`, `dkim_added`, `rl_saved`; errors
`domain_invalid`, `domain_exists`, `maxquota_empty`.
operationId: addDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
description: Domain name (stored lowercase, IDN as punycode)
description:
type: string
description: Description, default the domain name
template:
type: [integer, string]
description: ID of the domain template for fields not sent
aliases:
type: [integer, string]
description: Max. number of aliases
archive:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: >-
Archive mails of mailboxes set to `inherit` (admins, domain admins with
the `archive` ACL)
mailboxes:
type: [integer, string]
description: Max. number of mailboxes
defquota:
type: [integer, string]
description: Default quota of new mailboxes in MiB, must not be 0
maxquota:
type: [integer, string]
description: Max. quota per mailbox in MiB, must not be 0
quota:
type: [integer, string]
description: Quota of the whole domain in MiB
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Domain active
gal:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Global address list in SOGo
backupmx:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Relay this domain (backup MX)
relay_all_recipients:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: >-
Relay all recipients, not only those with a mailbox; 1 sets
`backupmx`
relay_unknown_only:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: >-
Relay only recipients without a local mailbox; 1 sets
`backupmx` and `relay_all_recipients`
tags:
type: array
items:
type: string
description: >-
Tags of the domain, at most 25 (more are dropped with
`tag_limit_exceeded`)
rl_value:
type: [integer, string]
description: Rate limit, messages per `rl_frame`; empty or 0 = none
rl_frame:
type: string
enum: [s, m, h, d]
description: Rate limit time frame
dkim_selector:
type: string
description: Selector of the DKIM key that is created
key_size:
type: [integer, string]
description: RSA size of the new DKIM key in bits; empty or 0 = no key
restart_sogo:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Restart SOGo afterwards
example:
domain: example.org
description: Example Org
aliases: 400
mailboxes: 10
defquota: 3072
maxquota: 10240
quota: 10240
active: 1
gal: 1
backupmx: 0
relay_all_recipients: 0
relay_unknown_only: 0
tags:
- customer
rl_value: 100
rl_frame: h
dkim_selector: dkim
key_size: 2048
restart_sogo: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/domain-admin:
post:
summary: Create domain administrator
description: >-
Creates a domain administrator for the given domains with the default
ACLs. The username is stored in lowercase and must not be in use by a
mailbox or administrator. Without `active: 1` the account is disabled.
Unknown domains are skipped; if none exists, nothing is created, but
`domain_admin_added` is reported anyway.
Messages: `domain_admin_added`; errors `domain_invalid`,
`object_exists`, `password_complexity`, `password_mismatch`.
operationId: addDomainAdmin
tags:
- Domain admin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Username (letters, digits, `_`, `.`, `-`; stored in lowercase)
password:
type: string
description: Password, must match the password policy
password2:
type: string
description: The password again
domains:
description: Domain or list of domains the account administers
oneOf:
- type: string
- type: array
items:
type: string
active:
type: [integer, string, boolean]
description: 1 = the account can log in, 0 = disabled
default: 0
required:
- username
- password
- password2
- domains
example:
username: domainadmin1
password: "Rand0m-Passw0rd!"
password2: "Rand0m-Passw0rd!"
domains:
- example.org
- example.com
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/sso/domain-admin:
post:
summary: Issue domain administrator login token
description: >-
Issues a one-time login token for an active domain administrator, valid
for 30 seconds. Opening `/domainadmin/mailbox?sso_token=<token>` on the
mailcow host logs in without password or two-factor authentication.
Messages: error `object_doesnt_exist`.
operationId: issueDomainAdminSsoToken
tags:
- Single Sign-On
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Username of the domain administrator
required:
- username
example:
username: domainadmin1
responses:
"200":
description: The token, or the error messages
content:
application/json:
schema:
oneOf:
- type: object
properties:
token:
type: string
description: Login token (five groups of six hex digits)
required:
- token
- $ref: "#/components/schemas/Messages"
example:
token: 591F6D-5C3DD2-7455CD-DAF1C1-AA4FCC
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/da-acl:
post:
summary: Edit domain administrator ACLs
description: >-
Grants the ACLs in `da_acl` and revokes all others; an empty or missing
`da_acl` revokes all.
Messages: `acl_saved`; error `Cannot determine current ACL`.
operationId: editDomainAdminAcl
tags:
- Domain admin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
description: Username of the domain administrator, or a list of usernames
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
da_acl:
description: The ACLs to grant (a single name or a list)
oneOf:
- $ref: "#/components/schemas/DomainAdminAcl"
- type: array
items:
$ref: "#/components/schemas/DomainAdminAcl"
required:
- items
- attr
example:
items:
- domainadmin1
attr:
da_acl:
- syncjobs
- quarantine
- login_as
- sogo_access
- app_passwds
- bcc_maps
- filters
- ratelimit
- spam_policy
- protocol_access
- smtp_ip_access
- mailbox_relayhost
- domain_relayhost
- alias_external_goto
- mailbox_groups
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/domain-admin:
post:
summary: Edit domain administrators
description: >-
Changes domain administrators. Fields not sent keep their value, but
`force_tfa` and `force_pw_update` are reset to 0. `domains` replaces
the domain list, empty keeps it; an empty `password` keeps the
password. FIDO2 keys are not moved on rename. A password error ends
the call after the domains were saved.
Messages: `domain_admin_modified`; errors `domain_invalid`,
`username_invalid`, `password_mismatch`, `password_complexity`.
operationId: editDomainAdmin
tags:
- Domain admin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
description: Username of the domain administrator, or a list of usernames
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
active:
type: [integer, string, boolean]
description: 1 = active, 0 = disabled
username_new:
type: string
description: New username (letters, digits, `_`, `.`, `-`)
domains:
description: The domains the account administers from now on
oneOf:
- type: string
- type: array
items:
type: string
password:
type: string
description: New password; empty or missing keeps the password
password2:
type: string
description: The new password again
force_tfa:
type: [integer, string, boolean]
description: 1 = two-factor authentication must be set up at the next login
default: 0
force_pw_update:
type: [integer, string, boolean]
description: 1 = the password must be changed at the next login
default: 0
disable_tfa:
type: [integer, string, boolean]
description: Present (any value) = turn off two-factor authentication
required:
- items
- attr
example:
items:
- domainadmin1
attr:
active: 1
domains:
- example.org
password: "N3w-Passw0rd!"
password2: "N3w-Passw0rd!"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/domain-policy:
post:
summary: Add a sender to a domain allow or deny list
description: >-
Adds a sender to the allow list (`wl`) or deny list (`bl`) of a domain;
a sender can be on only one list. Needs the ACL `spam_policy`.
Messages: `domain_modified`; errors `policy_list_from_invalid`,
`policy_list_from_exists`.
operationId: addDomainPolicy
tags:
- Domain antispam policies
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- object_list
- object_from
properties:
domain:
type: string
description: Domain the entry belongs to
object_list:
type: string
enum: [wl, bl]
description: "`wl` allow list (whitelist), `bl` deny list (blacklist)"
object_from:
type: string
description: >-
Sender address or pattern with `*` as wildcard; letters,
digits and `@ _ . - *`
example:
domain: example.org
object_list: wl
object_from: "*@partner.example.com"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/fwdhost:
post:
tags:
- Forwarding Hosts
summary: Add forwarding hosts
operationId: addForwardingHost
description: >-
Adds hosts whose mail is accepted unconditionally: no DNSBL checks, no
greylisting, no spam rejects. A name becomes one entry per address of
its SPF record, else its MX hosts, else A/AAAA.
Messages: `forwarding_host_added`; errors `invalid_host`.
requestBody:
content:
application/json:
schema:
type: object
properties:
hostname:
type: string
description: >-
IPv4 or IPv6 address, network in CIDR notation, host name
or domain name
filter_spam:
type: [boolean, integer, string]
description: 1 = scan the mail for spam (junk folder, never rejected); else not
default: 0
required:
- hostname
example:
hostname: relay.example.com
filter_spam: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/fwdhost:
post:
tags:
- Forwarding Hosts
summary: Update forwarding hosts
operationId: editForwardingHost
description: >-
Turns the spam filter of forwarding hosts on or off; without
`keep_spam` it is turned on.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: >-
Hosts as get/fwdhost lists them (`host`), a single value or
a list
oneOf:
- type: array
items:
type: string
- type: string
attr:
type: object
properties:
keep_spam:
type: [boolean, integer, string]
description: 1 = do not scan the mail for spam; else scan it
required:
- items
- attr
example:
items:
- 192.0.2.25
- "2001:db8::25"
attr:
keep_spam: "0"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/mailbox:
post:
tags:
- Mailboxes
summary: Create a mailbox
operationId: addMailbox
description: >-
Creates a mailbox, also for domain admins. Quotas are in MiB. Fields
not sent come from the mailbox template in `template` (default:
`Default`). Quota 0 (unlimited) needs the `unlimited_quota` ACL.
Messages: `mailbox_added`; errors `object_exists`, `domain_not_found`,
`password_complexity`, `max_mailbox_exceeded`,
`mailbox_quota_exceeded`.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxAdd"
example:
local_part: john.doe
domain: example.org
name: John Doe
password: Moo2Shoh5aiXu
password2: Moo2Shoh5aiXu
quota: 3072
active: 1
force_pw_update: 1
tags:
- sales
acl:
- spam_alias
- spam_score
- delimiter_action
- app_passwds
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/mailbox-group:
post:
summary: Create mailbox group
description: >-
Creates a mailbox group. With an address it is also a distribution list
to its members; the address counts against the alias limit of the
domain. Domain admins need the `mailbox_groups` ACL. Follow-up steps
that fail answer a warning and are retried later.
Messages: `group_added`; warnings `group_template_failed`,
`group_imap_grant_failed`; errors `object_exists`,
`group_address_invalid`, `max_alias_exceeded`, `group_member_invalid`.
operationId: addMailboxGroup
tags:
- Groups
requestBody:
content:
application/json:
schema:
allOf:
- type: object
required:
- domain
- name
properties:
domain:
type: string
description: Domain of the group (no alias domain), case-insensitive
- $ref: "#/components/schemas/MailboxGroupAttributes"
example:
domain: example.org
name: Sales
description: Sales team
local_part: sales
members:
- alice@example.org
- bob@example.org
send_as:
- orders@example.org
sender_allowed: 1
imap_grants:
- owner: shared@example.org
rights: write
subscribe: 1
template_id: 3
priority: 10
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/oauth2-client:
post:
summary: Create OAuth2 client
description: >-
Creates an OAuth2 client with random ID and secret; read them with
`get/oauth2-client/all`. The redirect URI is not validated.
Messages: `Added client access`.
operationId: addOAuth2Client
tags:
- oAuth Clients
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
redirect_uri:
type: string
description: Redirect (callback) URL of the client application
required:
- redirect_uri
example:
redirect_uri: https://app.example.org/oauth/callback
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/recipient_map:
post:
tags:
- Address Rewriting
summary: Create a recipient map
operationId: addRecipientMap
description: >-
Rewrites the recipient before delivery: mail to `recipient_map_old`
goes to `recipient_map_new`.
Messages: `recipient_map_entry_saved`; errors
`invalid_recipient_map_old`, `invalid_recipient_map_new`,
`recipient_map_entry_exists`.
requestBody:
content:
application/json:
schema:
type: object
properties:
recipient_map_old:
type: string
description: Original recipient, an e-mail address or a domain (leading `@` optional)
recipient_map_new:
type: string
description: New recipient, an e-mail address or a domain
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
default: 0
required:
- recipient_map_old
- recipient_map_new
example:
recipient_map_old: jane.doe@example.org
recipient_map_new: jane.smith@example.org
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/relayhost:
post:
tags:
- Routing
summary: Create a sender-dependent transport
operationId: addRelayhost
description: >-
Adds an active relay host, used by domains and mailboxes whose
`relayhost` is set to its ID. Always `smtp:` (TLS when offered, no
SMTPS). Colons in `username` and `password` are stored escaped, but
not by edit/relayhost.
Messages: `relayhost_added`; errors `invalid_host`.
requestBody:
content:
application/json:
schema:
type: object
properties:
hostname:
type: string
description: "Next hop: `host`, `host:25`, `[host]:587` or `[192.0.2.1]:25`"
username:
type: string
description: SMTP user name, empty for no authentication
default: ""
password:
type: string
description: SMTP password
default: ""
required:
- hostname
example:
hostname: "[smtp.example.com]:587"
username: relay-user@example.com
password: Secret-Passphrase-42
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/resource:
post:
tags:
- Resources
summary: Create a resource
operationId: addResource
description: >-
Creates a bookable SOGo resource, also for domain admins. Its address
is made of the letters and digits of `description` (`Meeting Room 1` →
`MeetingRoom1@example.org`).
Messages: `resource_added`; errors `resource_invalid`,
`description_invalid`, `object_exists`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- description
- kind
properties:
domain:
type: string
description: Domain of the resource
description:
type: string
description: Name of the resource, also the source of its address
kind:
type: string
enum:
- location
- group
- thing
description: Type of resource
multiple_bookings:
type: [integer, string]
default: 0
description: >-
0 always free, -1 unlimited but busy when booked, n ≥ 1 at
most n overlapping bookings; below -1 means -1
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: 1 active, 0 inactive
example:
domain: example.org
description: Meeting Room 1
kind: location
multiple_bookings: 0
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/syncjob:
post:
summary: Create sync job
description: >-
Creates a sync job that copies the remote account `user1` into a local
mailbox; server and authentication come from the sync source. Needs the
`syncjobs` ACL; API keys must set `username`, users always sync into
their own mailbox. An invalid `mins_interval` or `exclude` answers
`access_denied`.
Messages: `mailbox_modified`; errors `no_user_defined`,
`imapsync_source_unavailable`, `imapsync_source_oauth_connect_required`,
`object_exists`, `imapsync_custom_param_invalid`.
operationId: addSyncJob
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
allOf:
- type: object
required:
- username
- source_id
- user1
- mins_interval
properties:
username:
type: string
description: >-
Local mailbox to sync into (`user2`), cannot be changed
later; users may leave it out
- $ref: "#/components/schemas/SyncJobAttributes"
example:
username: alice@example.org
source_id: 3
user1: alice@old-provider.example.com
password1: remote-password
mins_interval: 20
subfolder2: Imported
exclude: "(?i)spam|(?i)junk"
custom_params:
- o: folder
v: INBOX
delete2duplicates: 1
automap: 1
subscribeall: 1
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/syncjob_source:
post:
summary: Create sync source
description: >-
Creates a reusable IMAP server with its authentication that sync jobs
use by `source_id`. Needs the `syncjobs` ACL. Unless an admin creates
it, OAuth2 endpoints must resolve to public addresses. A
client_credentials source fetches its token on save and is saved even
when that fails.
Messages: `imapsync_source_added`, `imapsync_source_token_refresh_failed`;
errors `imapsync_source_host_invalid`, `imapsync_source_auth_invalid`,
`imapsync_source_oauth_invalid`, `imapsync_source_oauth_endpoint_invalid`,
`object_exists`.
operationId: addSyncJobSource
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
allOf:
- type: object
required:
- name
- host
- port
- $ref: "#/components/schemas/SyncJobSourceAttributes"
examples:
password:
summary: Password source for a domain
value:
name: Old provider
description: Migration from the old provider
host: imap.example.com
port: 993
enc: SSL
auth_type: PLAIN
scope: domain
domains:
- example.org
active: 1
client_credentials:
summary: XOAUTH2 source with an app token (Microsoft 365)
value:
name: M365 tenant
host: outlook.office365.com
port: 993
enc: SSL
auth_type: XOAUTH2
oauth_flow: client_credentials
oauth_token_endpoint: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token
oauth_client_id: 11111111-2222-3333-4444-555555555555
oauth_client_secret: client-secret-value
oauth_scope: https://outlook.office365.com/.default
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/tls-policy-map:
post:
tags:
- Outgoing TLS Policy Map Overrides
summary: Create a TLS policy map
operationId: addTlsPolicyMap
description: >-
Sets the TLS policy for outgoing connections to a destination.
Messages: `tls_policy_map_entry_saved`; errors
`tls_policy_map_dest_invalid`, `tls_policy_map_parameter_invalid`,
`tls_policy_map_entry_exists`.
requestBody:
content:
application/json:
schema:
type: object
properties:
dest:
type: string
description: >-
Destination: a domain, `.example.org` for its subdomains or
a host like `[mail.example.org]:25`
policy:
type: string
description: >-
Postfix TLS security level (see
[smtp_tls_policy_maps](https://www.postfix.org/TLS_README.html#client_tls_policy))
enum:
- none
- may
- encrypt
- dane
- dane-only
- fingerprint
- verify
- secure
parameters:
type: string
description: Space-separated `name=value` attributes, may be empty
default: ""
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
default: 0
required:
- dest
- policy
example:
dest: example.com
policy: encrypt
parameters: protocols=>=TLSv1.2
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/transport:
post:
tags:
- Routing
summary: Create transport maps
operationId: addTransport
description: >-
Routes mail for each destination over a next hop; overrules
sender-dependent transports. Always `smtp:` (TLS when offered, no
SMTPS); addresses ending in `localhost` stay local. `username` and
`password` apply to all entries of the next hop.
Messages: `relayhost_added`; errors `transport_dest_exists`,
`invalid_destination`, `next_hop_interferes`,
`invalid_nexthop_authenticated`.
requestBody:
content:
application/json:
schema:
type: object
properties:
destination:
type: string
description: >-
Domains, `.example.org` for subdomains, `*` or addresses,
separated by spaces, commas, semicolons or line breaks;
with `is_mx_based` a regular expression for the MX name of
the recipient domain
nexthop:
type: string
description: "`host`, `host:25`, `[host]:25` or an IP address (bracketed automatically)"
username:
type: string
description: SMTP user name, empty for no authentication
default: ""
password:
type: string
description: SMTP password
default: ""
is_mx_based:
type: [boolean, integer, string]
description: 1 = `destination` is a regular expression for MX names
default: 0
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
default: 0
required:
- destination
- nexthop
example:
destination: example.com, .example.com
nexthop: "[mx.example.com]:25"
username: ""
password: ""
is_mx_based: "0"
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/alias:
post:
tags:
- Aliases
summary: Delete aliases
operationId: deleteAlias
description: >-
Deletes the aliases and the send-as rights granted for their addresses.
Distribution addresses of mailbox groups cannot be deleted here.
Messages: `alias_removed`; errors `alias_group_managed`.
requestBody:
content:
application/json:
schema:
type: array
description: IDs or addresses of the aliases (a single value works too)
items:
type: [integer, string]
example:
- 12
- info@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/api-key:
post:
summary: Delete API keys
description: >-
Deletes API keys. Service keys from mailcow.conf cannot be deleted.
Messages: `api_key_deleted`; error `api_key_service_locked`.
operationId: deleteApiKey
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
type: array
description: IDs of the API keys
items:
type: [integer, string]
example:
- 3
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/app-passwd:
post:
tags:
- App Passwords
summary: Delete app passwords
operationId: deleteAppPassword
description: >-
Deletes app passwords by ID. Needs the user ACL `app_passwds`. The
first unknown or foreign ID stops the call.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: App password IDs
items:
type: integer
example:
- 23
- 24
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/bcc:
post:
tags:
- Address Rewriting
summary: Delete BCC maps
operationId: deleteBccMap
description: >-
Deletes BCC maps by ID. Same callers as add/bcc. A non-numeric ID stops
the call.
Messages: `bcc_deleted`.
requestBody:
content:
application/json:
schema:
type: array
description: IDs of the BCC maps (a single value works too)
items:
type: [integer, string]
example:
- 3
- 4
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/dkim:
post:
summary: Delete DKIM keys
description: >-
Deletes the DKIM keys of domains. Answers `dkim_removed` also for
domains without a key.
operationId: deleteDkimKeys
tags:
- DKIM
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Domain names
items:
type: string
example:
- example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/domain:
post:
summary: Delete domains
description: >-
Deletes domains without mailboxes or resources, with their aliases,
alias domains and settings. Domain admins left without a domain are
deleted too. The DKIM key is kept.
Messages: `domain_removed`; error `domain_not_empty`.
operationId: deleteDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Domain names
items:
type: string
example:
- example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/domain-admin:
post:
summary: Delete domain administrators
description: >-
Deletes domain administrators with their ACLs, two-factor
authentication and FIDO2 keys.
Messages: `domain_admin_removed`; error `username_invalid`.
operationId: deleteDomainAdmin
tags:
- Domain admin
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Usernames of the domain administrators
items:
type: string
example:
- domainadmin1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/domain-policy:
post:
summary: Delete entries of domain allow and deny lists
description: >-
Deletes allow and deny list entries of domains by `prefid`. Needs the
ACL `spam_policy`. Unknown IDs and entries of mailboxes answer
`access_denied`.
Messages: `item_deleted`.
operationId: deleteDomainPolicy
tags:
- Domain antispam policies
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Entry IDs (`prefid`)
items:
type: [integer, string]
example:
- 12
- 13
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/fwdhost:
post:
tags:
- Forwarding Hosts
summary: Delete forwarding hosts
operationId: deleteForwardingHost
description: >-
Removes forwarding hosts, answering `forwarding_host_removed` also for
hosts that do not exist.
requestBody:
content:
application/json:
schema:
type: array
description: Hosts as get/fwdhost lists them (`host`; a single value works too)
items:
type: string
example:
- 192.0.2.25
- "2001:db8::25"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/fwdhost/{host}:
get:
tags:
- Forwarding Hosts
summary: Get forwarding hosts
operationId: getForwardingHosts
description: >-
`all` lists the forwarding hosts; any logged-in role may read a single
address. Networks cannot be read one by one (the slash ends the path).
`{}` if there is none.
parameters:
- name: host
in: path
required: true
description: "`all` or the address of a forwarding host"
schema:
type: string
example: all
responses:
"200":
description: The list of forwarding hosts (`all`) or one host
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/ForwardingHost"
- $ref: "#/components/schemas/ForwardingHost"
examples:
all:
summary: get/fwdhost/all
value:
- host: 192.0.2.25
source: relay.example.com
keep_spam: "no"
- host: "2001:db8::25"
source: relay.example.com
keep_spam: "no"
- host: 198.51.100.0/24
source: 198.51.100.0/24
keep_spam: "yes"
one:
summary: get/fwdhost/192.0.2.25
value:
host: 192.0.2.25
source: relay.example.com
keep_spam: "no"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/delete/mailbox:
post:
tags:
- Mailboxes
summary: Delete mailboxes
operationId: deleteMailbox
description: >-
Deletes mailboxes with all their data, including aliases that point
only to them. Also for domain admins; a mailbox user can delete its own
mailbox.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxItems"
example:
- john.doe@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/mailbox-group:
post:
summary: Delete mailbox groups
description: >-
Deletes groups with their address, send-as rights and grants. Members
keep their mailbox settings; another group's template may become
effective. Same permissions as edit.
Messages: `group_removed`.
operationId: deleteMailboxGroups
tags:
- Groups
requestBody:
content:
application/json:
schema:
type: array
description: Group ids
items:
type:
- integer
- string
example:
- 7
- 8
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/identity-link:
post:
summary: Remove identity links
description: >-
Removes the links of mailboxes to their Identity Provider users, e.g.
after an address moved to another user; the next sync run or login
links them again by email. Answers success also for mailboxes without a
link.
Messages: `iam_link_removed`.
operationId: deleteIdentityLinks
tags:
- Identity Provider
requestBody:
content:
application/json:
schema:
type: array
description: Mailboxes
items:
type: string
example:
- alice@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/mailq:
post:
summary: Delete queued messages
description: >-
Deletes messages from the Postfix queue. To empty the whole queue use
`super_delete` of `POST /api/v1/edit/mailq`.
Messages: `queue_command_success`; errors `Error: command failed: ...`,
`unknown`.
operationId: deleteQueuedMessages
tags:
- Queue Manager
requestBody:
content:
application/json:
schema:
description: Queue IDs (a single ID works too)
oneOf:
- type: array
items:
type: string
- type: string
example:
- B98C6260CA1
- 4C1E8260D02
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/oauth2-client:
post:
summary: Delete OAuth2 clients
description: >-
Deletes OAuth2 clients but not their tokens; revoke these first with
`revoke_tokens` of `edit/oauth2-client`.
Messages: `items_deleted`.
operationId: deleteOAuth2Client
tags:
- oAuth Clients
requestBody:
required: true
content:
application/json:
schema:
type: array
description: IDs of the clients
items:
type: [integer, string]
example:
- 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/qitem:
post:
summary: Delete quarantined messages
description: >-
Deletes quarantine items without releasing or learning them. Domain
admins and mailbox users may delete their own items if the quarantine
module is allowed for them. Admins get `item_deleted` even for unknown
IDs.
operationId: deleteQuarantineItems
tags:
- Quarantine
requestBody:
content:
application/json:
schema:
description: IDs of quarantine items (a single ID works too)
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
example:
- "33"
- "34"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/qitem:
post:
summary: Release or learn quarantined messages
description: >-
By `attr.action`: `release` and `learnham` both deliver the message,
delete the item and learn it as ham; `learnspam` deletes it and learns
it as spam. Domain
admins and mailbox users may act on their own items if the quarantine
module is allowed for them. A failed delivery stops the remaining
items.
Messages: `item_released`, `learned_ham`, `qlearn_spam`; errors
`release_send_failed`, `ham_learn_error`, `spam_learn_error`.
operationId: editQuarantineItems
tags:
- Quarantine
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: ID or list of IDs of quarantine items
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
action:
type: string
enum:
- release
- learnham
- learnspam
required:
- action
required:
- items
- attr
example:
items:
- "33"
- "34"
attr:
action: release
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/recipient_map:
post:
tags:
- Address Rewriting
summary: Delete recipient maps
operationId: deleteRecipientMap
description: >-
Deletes recipient maps by ID. Answers `recipient_map_entry_deleted`
also for IDs that do not exist; a non-numeric ID stops the call.
requestBody:
content:
application/json:
schema:
type: array
description: IDs of the recipient maps (a single value works too)
items:
type: [integer, string]
example:
- 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/relayhost:
post:
tags:
- Routing
summary: Delete sender-dependent transports
operationId: deleteRelayhost
description: >-
Deletes sender-dependent transports by ID, answering
`relayhost_removed` also for IDs that do not exist. Domains that used
one fall back to the default route; the `relayhost` of mailboxes is not
reset.
requestBody:
content:
application/json:
schema:
type: array
description: IDs of the sender-dependent transports (a single value works too)
items:
type: [integer, string]
example:
- 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/resource:
post:
tags:
- Resources
summary: Delete resources
operationId: deleteResource
description: >-
Deletes resources and their SOGo data, also for domain admins.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Resource addresses
items:
type: string
example:
- MeetingRoom1@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/syncjob:
post:
summary: Delete sync jobs
description: >-
Deletes sync jobs. Needs the `syncjobs` ACL and access to the mailbox of
each job. The OAuth2 token of the remote account is deleted when no
other job uses it.
Messages: `deleted_syncjob`.
operationId: deleteSyncJobs
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: array
description: Job ids
items:
type:
- integer
- string
example:
- 12
- 13
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/syncjob_source:
post:
summary: Delete sync sources
description: >-
Deletes sync sources that no job uses. Needs the `syncjobs` ACL and edit
rights on the source.
Messages: `imapsync_source_deleted`; errors `imapsync_source_in_use`.
operationId: deleteSyncJobSources
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: array
description: Source ids
items:
type:
- integer
- string
example:
- 3
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/tls-policy-map:
post:
tags:
- Outgoing TLS Policy Map Overrides
summary: Delete TLS policy maps
operationId: deleteTlsPolicyMap
description: >-
Deletes TLS policy maps by ID. Answers `tls_policy_map_entry_deleted`
also for IDs that do not exist; a non-numeric ID stops the call.
requestBody:
content:
application/json:
schema:
type: array
description: IDs of the TLS policy maps (a single value works too)
items:
type: [integer, string]
example:
- 2
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/transport:
post:
tags:
- Routing
summary: Delete transport maps
operationId: deleteTransport
description: >-
Deletes transport maps by ID, answering `relayhost_removed` also for
IDs that do not exist.
requestBody:
content:
application/json:
schema:
type: array
description: IDs of the transport maps (a single value works too)
items:
type: [integer, string]
example:
- 4
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/mailbox/tag/{mailbox}:
post:
tags:
- Mailboxes
summary: Remove tags from a mailbox
operationId: deleteMailboxTags
description: >-
Removes tags from the mailbox, also for domain admins. Answers "Cannot
delete item" when no tag was sent.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Tag names
items:
type: string
example:
- sales
- trainee
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/domain/tag/{domain}:
post:
summary: Remove tags of a domain
description: >-
Removes tags from a domain. Answers `domain_modified` also for tags the
domain did not have.
operationId: deleteDomainTags
tags:
- Domains
parameters:
- name: domain
in: path
required: true
description: Domain name
schema:
type: string
example: example.org
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Tag names
items:
type: string
example:
- customer
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/alias:
post:
tags:
- Aliases
summary: Update aliases
operationId: editAlias
description: >-
Changes the aliases in `items`; fields not sent keep their value,
except the `goto_*` flags, which are reset to 0. An alias that discards
or learns its mail therefore needs its `goto_*` flag in every edit,
else nothing is saved while the answer still says `alias_modified`.
Invalid destinations are dropped; if none remains, nothing is saved.
Messages: `alias_modified`; errors `alias_invalid`,
`alias_group_managed`, `goto_invalid`, `is_not_primary_alias`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs or addresses of the aliases, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
address:
type: string
description: New alias address, `@example.org` for a catch-all
goto:
type: string
description: >-
New destination addresses, replacing the current ones;
ignored if a `goto_*` flag is 1
goto_null:
type: [boolean, integer, string]
description: 1 = discard the mail silently
default: 0
goto_spam:
type: [boolean, integer, string]
description: 1 = learn the mail as spam
default: 0
goto_ham:
type: [boolean, integer, string]
description: 1 = learn the mail as ham
default: 0
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
sogo_visible:
type: [boolean, integer, string]
description: 1 = selectable sender in SOGo
internal:
type: [boolean, integer, string]
description: 1 = only reachable from its own domain and its alias domains
sender_allowed:
type: [boolean, integer, string]
description: 1 = the destination mailboxes may send as this alias
public_comment:
type: string
description: Comment shown to the users
private_comment:
type: string
description: Comment for administrators
expand_alias:
type: [boolean, integer]
description: >-
1 = only create the missing copies of the alias in the
alias domains of its domain; other attributes are
ignored
required:
- items
- attr
example:
items:
- 12
attr:
goto: anna@example.org,ben@example.org,carla@example.org
active: "1"
public_comment: Sales team
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/api-key:
post:
summary: Edit API keys
description: >-
Changes API keys; fields not sent keep their value. `regen_key` sets a
new random value, which locks out clients using the old one. Service
keys from mailcow.conf cannot be changed.
Messages: `api_key_modified`; errors `api_key_service_locked`,
`api_key_network_invalid`, `ip_list_empty`.
operationId: editApiKey
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
description: ID of the API key, or a list of IDs
oneOf:
- type: [integer, string]
- type: array
items:
type: [integer, string]
attr:
allOf:
- $ref: "#/components/schemas/ApiKeyAttributes"
- type: object
properties:
regen_key:
type: [integer, string, boolean]
description: 1 = generate a new key value
default: 0
required:
- items
- attr
example:
items:
- 3
attr:
allow_from:
- 192.0.2.10
- 198.51.100.0/24
regen_key: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/domain:
post:
summary: Edit domains
description: >-
Changes domains. Quotas are in MiB. Fields not sent keep their value,
so do `aliases`, `maxquota` and `quota` sent as 0 or empty. `tags` are
added; a tag the domain has already ends the call without an answer
after saving the rest. Domain admins can change only `description`,
`gal` and `tags`.
Messages: `domain_modified`; errors `domain_invalid`,
`max_quota_in_use`, `mailboxes_in_use`, `aliases_in_use`.
operationId: editDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Domain name or list of domain names
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
description:
type: string
description: Description
aliases:
type: [integer, string]
description: Max. number of aliases
archive:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: >-
Archive mails of mailboxes set to `inherit` (admins, domain admins with
the `archive` ACL)
mailboxes:
type: [integer, string]
description: Max. number of mailboxes
defquota:
type: [integer, string]
description: Default quota of new mailboxes in MiB
maxquota:
type: [integer, string]
description: Max. quota per mailbox in MiB
quota:
type: [integer, string]
description: Quota of the whole domain in MiB
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Domain active
gal:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Global address list in SOGo
backupmx:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Relay this domain (backup MX)
relay_all_recipients:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Relay all recipients; 1 sets `backupmx`
relay_unknown_only:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: >-
Relay only recipients without a local mailbox; 1 sets
`backupmx` and `relay_all_recipients`
relayhost:
type: [integer, string]
description: >-
ID of the sender-dependent transport (get/relayhost/all)
the domain sends through, 0 = none
tags:
type: array
items:
type: string
description: Tags to add
example:
items:
- example.org
attr:
description: Example Org
aliases: 400
mailboxes: 20
defquota: 3072
maxquota: 10240
quota: 51200
active: 1
gal: 1
backupmx: 0
relay_all_recipients: 0
relay_unknown_only: 0
relayhost: 0
tags:
- premium
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/domain/footer:
post:
summary: Set the domain-wide footer
description: >-
Sets the footer of all outgoing mail of the domains; fields not sent are
emptied. Placeholders: `{= auth_user =}`, `{= from_user =}`,
`{= from_name =}`, `{= from_addr =}`, `{= from_domain =}` and custom
mailbox attributes.
Messages: `domain_footer_modified`; error `domain_invalid`.
operationId: editDomainFooter
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Domain name or list of domain names
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
html:
type: string
default: ""
description: HTML footer
plain:
type: string
default: ""
description: Plain text footer
skip_replies:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: No footer in replies
exclude:
description: >-
Mailboxes, aliases and alias domains without footer;
unknown entries are skipped (`username_invalid`)
oneOf:
- type: string
- type: array
items:
type: string
example:
items:
- example.org
attr:
html: "<p>Example Org &middot; {= from_name =}</p>"
plain: "Example Org - {= from_name =}"
skip_replies: 1
exclude:
- noreply@example.org
- example.com
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/fail2ban:
post:
summary: Edit Fail2Ban settings, bans and filters
description: >-
By `attr.action`: `unban`, `whitelist` and `blacklist` unban, allowlist
or deny the networks in `items`; `unban-all` lifts all active bans;
`edit-regex` replaces the regex filters with `attr.regex`,
`reset-regex` restores the defaults. Without `action` the settings are
saved: fields not sent keep their value, but `ban_time_increment` and
`manage_external` become 0, and values out of range are clamped. The
same happens for `unban`, `whitelist`, `blacklist` or `reset-regex`
without `items`.
Messages: `f2b_modified`, `object_modified`; errors
`network_host_invalid`, `reset_f2b_regex`.
operationId: editFail2Ban
tags:
- Fail2Ban
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: Networks or IPs for `unban`, `whitelist`, `blacklist` (single value or list)
oneOf:
- type: array
items:
type: string
- type: string
attr:
type: object
properties:
action:
type: string
enum:
- unban
- whitelist
- blacklist
- unban-all
- edit-regex
- reset-regex
regex:
type: array
items:
type: string
description: "`edit-regex`: the regex filters; the first group must match the IP"
ban_time:
type: [integer, string]
description: Ban time in seconds (min. 60)
ban_time_increment:
type: [boolean, integer, string]
description: 1 = the ban time grows with every ban of a network; not sent = 0
max_ban_time:
type: [integer, string]
description: Maximum ban time in seconds (min. 60)
max_attempts:
type: [integer, string]
description: Failed logins within `retry_window` that lead to a ban (min. 1)
retry_window:
type: [integer, string]
description: Window in seconds for `max_attempts` (min. 1)
netban_ipv4:
type: [integer, string]
description: IPv4 prefix length that is banned (8-32)
netban_ipv6:
type: [integer, string]
description: IPv6 prefix length that is banned (8-128)
whitelist:
type: string
description: Allowlist, networks or host names separated by space, comma, semicolon or newline; replaces the list
blacklist:
type: string
description: Denylist, networks separated by space, comma, semicolon or newline; replaces the list
manage_external:
type: [boolean, integer, string]
description: 1 = netfilter sets no rules, block externally with the banlist; not sent = 0
required:
- attr
examples:
settings:
summary: Save the settings
value:
items: []
attr:
ban_time: "1800"
ban_time_increment: "1"
max_ban_time: "86400"
max_attempts: "10"
retry_window: "600"
netban_ipv4: "32"
netban_ipv6: "128"
whitelist: |-
192.0.2.0/24
mail.example.org
blacklist: 198.51.100.66/32
manage_external: "0"
unban:
summary: Unban a network
value:
items:
- 203.0.113.7/32
attr:
action: unban
regex:
summary: Replace the regex filters
value:
items:
- self
attr:
action: edit-regex
regex:
- "^mailcow UI: Invalid password for .+ by ([0-9a-f\\.:]+)$"
- "^Rspamd UI: Invalid password by ([0-9a-f\\.:]+)$"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mailbox:
post:
tags:
- Mailboxes
summary: Update mailboxes
operationId: editMailbox
description: >-
Changes mailboxes; fields not sent keep their value. Also for domain
admins; without the matching ACL their changes to `sogo_access`,
protocols and `relayhost` are ignored silently and
`extended_sender_acl` is refused. Quota 0 (unlimited) needs the
`unlimited_quota` ACL.
Messages: `mailbox_modified`; errors `mailbox_quota_exceeded`,
`password_complexity`, `sender_acl_invalid`,
`extended_sender_acl_denied`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
$ref: "#/components/schemas/MailboxEdit"
example:
items:
- john.doe@example.org
attr:
name: John Doe
quota: 5120
active: 1
protocol_access:
- imap
- smtp
- sieve
- dav
sender_acl:
- sales@example.org
- "@example.com"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mailbox/custom-attribute:
post:
tags:
- Mailboxes
summary: Set custom attributes of mailboxes
operationId: editMailboxCustomAttributes
description: >-
Replaces the custom attributes (free key/value pairs) of the mailboxes:
`attribute[i]` gets `value[i]`, all others are removed. Also for domain
admins.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
properties:
attribute:
description: Attribute names (a single string is one name)
oneOf:
- type: string
- type: array
items:
type: string
value:
description: Values, in the order of `attribute`
oneOf:
- type: string
- type: array
items:
type: string
example:
items:
- john.doe@example.org
attr:
attribute:
- department
- employee_id
value:
- Sales
- "4711"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mailbox-group:
post:
summary: Update mailbox groups
description: >-
Changes groups; fields not sent keep their value. The domain cannot be
changed, and members from the identity sync cannot be removed here.
Domain admins need the `mailbox_groups` ACL and cannot edit groups with
send-as addresses or grants outside their domains.
Messages: `group_modified`; errors `group_member_idp` and those of add.
operationId: editMailboxGroups
tags:
- Groups
requestBody:
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: >-
Group ids, a list or a single id. An `id` inside `attr`
replaces `items`.
oneOf:
- type: array
items:
type:
- integer
- string
- type:
- integer
- string
attr:
allOf:
- $ref: "#/components/schemas/MailboxGroupAttributes"
- type: object
properties:
reapply_template:
type:
- boolean
- integer
- string
description: >-
Admins only: apply the effective templates to all
members again, also when nothing changed
default: 0
example:
items:
- 7
attr:
add_members:
- carol@example.org
remove_members:
- bob@example.org
sogo_grants:
- owner: shared@example.org
type: Calendar
folder: personal
access: write
subscribe: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/identity-provider-sync:
post:
summary: Request an identity sync run
description: >-
Queues an identity sync run (Keycloak and LDAP) that starts within a
minute, see `GET /api/v1/get/identity-provider/sync-status`. An
identical pending request is reused.
Messages: `iam_sync_requested`; errors `iam_sync_mode_invalid`,
`iam_sync_unavailable`.
operationId: requestIdentitySync
tags:
- Identity Provider
requestBody:
content:
application/json:
schema:
type: object
required:
- attr
properties:
items:
description: Not used
attr:
type: object
properties:
mode:
type: string
description: >-
`preview` lists the changes without applying them,
`run` applies them, `force` applies them without the
change limit (`offboarding_limit`)
enum:
- preview
- run
- force
default: run
example:
attr:
mode: preview
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mailq:
post:
summary: Act on the mail queue
description: >-
Runs a Postfix queue command. `hold`, `unhold` and `deliver` act on the
queue IDs in `items` and do nothing without them; `flush` retries the
whole queue, `super_delete` deletes every queued message.
Messages: `queue_command_success`; errors `Error: command failed: ...`,
`unknown`.
operationId: editMailQueue
tags:
- Queue Manager
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: Queue ID or list of queue IDs (for `hold`, `unhold`, `deliver`)
oneOf:
- type: array
items:
type: string
- type: string
attr:
type: object
properties:
action:
type: string
enum:
- hold
- unhold
- deliver
- flush
- super_delete
required:
- action
required:
- attr
examples:
hold:
summary: Hold two messages
value:
items:
- B98C6260CA1
- 4C1E8260D02
attr:
action: hold
flush:
summary: Flush the whole queue
value:
items: []
attr:
action: flush
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/pushover:
post:
tags:
- Mailbox user settings
summary: Set the Pushover notifications of mailboxes
operationId: editPushover
description: >-
Saves the Pushover settings (push notification on new mail) of the
mailboxes; `delete: "true"` removes them. Needs the user ACL
`pushover`; domain admins need their own ACL `pushover`. `key` and
`token` are required the first time; later, empty fields keep their
value.
Messages: `pushover_settings_edited`; errors `pushover_key`,
`pushover_token`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
properties:
key:
type: string
description: Pushover user key, 30 letters and digits
token:
type: string
description: Pushover application token, 30 letters and digits
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
title:
type: string
description: Title of the notification (default "Mail")
text:
type: string
description: Text of the notification
senders:
type: string
description: Only notify for these senders (separated by comma, space or semicolon)
senders_regex:
type: string
description: Only notify for senders matching this regular expression
evaluate_x_prio:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: 1 sends high-priority mail as high-priority notification (0 when not sent)
only_x_prio:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: 1 notifies for high-priority mails only (0 when not sent)
sound:
type: string
description: Pushover sound name (empty when not sent)
delete:
type: string
enum:
- "true"
description: '"true" removes the Pushover settings, other fields are ignored'
example:
items:
- john.doe@example.org
attr:
key: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
token: azGDORePK8gMaC0QOYAMyEEuzJnyUi
active: 1
title: New mail
text: You've got mail
senders: boss@example.org
evaluate_x_prio: 1
only_x_prio: 0
sound: pushover
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/quarantine_notification:
post:
tags:
- Quarantine
summary: Set the quarantine notification interval of mailboxes
operationId: editQuarantineNotification
description: >-
How often the mailbox user gets a summary of quarantined mail. Needs
the user ACL `quarantine_notification`; a mailbox user may change only
its own. An invalid value answers `access_denied`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
required:
- quarantine_notification
properties:
quarantine_notification:
type: string
enum:
- never
- hourly
- daily
- weekly
example:
items:
- john.doe@example.org
attr:
quarantine_notification: daily
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/syncjob:
post:
summary: Update sync jobs
description: >-
Changes sync jobs; fields not sent keep their value, an empty `user1` or
`password1` keeps the stored one. The local mailbox cannot be changed.
Needs the `syncjobs` ACL and access to the mailbox of each job.
Messages: `mailbox_modified`; errors as for add.
operationId: editSyncJobs
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: >-
Job ids, a list or a single id. An `id` inside `attr`
replaces `items`.
oneOf:
- type: array
items:
type:
- integer
- string
- type:
- integer
- string
attr:
allOf:
- $ref: "#/components/schemas/SyncJobAttributes"
- type: object
properties:
last_run:
description: Any value except null resets the last run time (the job is due again)
success:
description: Any value except null resets the result of the last run
prio:
type:
- integer
- string
description: >-
Admins only: queue priority, higher runs first (see
`edit/syncjob/run_next`)
example:
items:
- 12
- 13
attr:
active: 0
mins_interval: 60
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/syncjob/run_next:
post:
summary: Run sync jobs next
description: >-
Moves sync jobs to the front of the queue so the runner starts them
next; their `last_run` and `success` are cleared.
Messages: `imapsync_run_next_done`; errors `imapsync_job_running`.
operationId: runSyncJobsNext
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
description: Job ids
type: array
items:
type:
- integer
- string
attr:
description: Not used
type: object
example:
items:
- 12
attr: {}
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/syncjob_source:
post:
summary: Update sync sources
description: >-
Changes sync sources; fields not sent keep their value, an empty
`oauth_client_secret` keeps the stored one. Needs the `syncjobs` ACL and
edit rights: own sources, for domain admins also those of their
mailboxes. Changing the server or OAuth2 client drops stored tokens and,
like turning off `verify_cert`, needs access to every mailbox whose jobs
use the source.
Messages: `imapsync_source_modified`,
`imapsync_source_token_refresh_failed`; errors
`imapsync_source_used_by_others` and those of add.
operationId: editSyncJobSources
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: >-
Source ids, a list or a single id. An `id` inside `attr`
replaces `items`.
oneOf:
- type: array
items:
type:
- integer
- string
- type:
- integer
- string
attr:
$ref: "#/components/schemas/SyncJobSourceAttributes"
example:
items:
- 3
attr:
description: Migration finished in December
scope: user
users:
- alice@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/syncjob_source/refresh_token:
post:
summary: Refresh the token of a sync source
description: >-
Fetches a new OAuth2 token for a client_credentials source now; tokens
are otherwise refreshed before they expire. Needs the `syncjobs` ACL and
edit rights on the source.
Messages: `imapsync_source_token_refreshed`; errors
`imapsync_source_refresh_unsupported`,
`imapsync_source_token_refresh_failed`.
operationId: refreshSyncJobSourceToken
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
description: Source id (the first entry is used)
type: array
items:
type:
- integer
- string
attr:
description: Not used
type: object
example:
items:
- 5
attr: {}
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/imapsync_settings:
post:
summary: Update global sync job settings
description: >-
Sets how many sync jobs run at the same time and the bandwidth limit of
each sync job process; a lower `maxbytespersecond` of a job still
applies.
Messages: `max_parallel_saved`; errors `imapsync_max_parallel_invalid`,
`imapsync_max_kb_per_second_invalid`.
operationId: editSyncJobSettings
tags:
- Sync jobs
requestBody:
content:
application/json:
schema:
type: object
required:
- attr
properties:
items:
description: Not used
attr:
type: object
required:
- max_parallel
properties:
max_parallel:
type:
- integer
- string
description: Sync jobs running at the same time, 1-32
minimum: 1
maximum: 32
max_kb_per_second:
type:
- integer
- string
description: Bandwidth limit per sync job process in KB/s; 0, empty or not sent = unlimited
default: 0
minimum: 0
maximum: 10485760
example:
attr:
max_parallel: 4
max_kb_per_second: 2000
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/user-acl:
post:
tags:
- Mailboxes
summary: Set the ACL of mailboxes
operationId: editUserAcl
description: >-
Sets the user ACL (what the mailbox user may change in the UI): listed
ACLs on, all others off. Domain admins can change only ACLs they have
themselves. Answers `acl_saved`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
properties:
user_acl:
description: ACLs to switch on (a single string is one ACL); an empty list switches all off
oneOf:
- $ref: "#/components/schemas/UserAclName"
- type: array
items:
$ref: "#/components/schemas/UserAclName"
example:
items:
- john.doe@example.org
attr:
user_acl:
- spam_alias
- tls_policy
- spam_score
- spam_policy
- delimiter_action
- eas_reset
- pushover
- quarantine
- quarantine_notification
- app_passwds
- pw_reset
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/alias/{id}:
get:
tags:
- Aliases
summary: Get aliases
operationId: getAliases
description: >-
`all` lists the aliases of the domains the caller manages, an ID or
address returns one alias. Mailbox addresses are not listed. `{}` if
there is none.
parameters:
- name: id
in: path
required: true
description: "`all`, or the ID or address of an alias"
schema:
type: string
example: all
responses:
"200":
description: The list of aliases (`all`) or one alias
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/Alias"
- $ref: "#/components/schemas/Alias"
examples:
all:
summary: get/alias/all
value:
- in_primary_domain: ""
id: 12
domain: example.org
public_comment: Sales team
private_comment: null
goto: anna@example.org,ben@example.org
address: sales@example.org
is_catch_all: 0
internal: 0
active: 1
active_int: 1
sogo_visible: 1
sogo_visible_int: 1
sender_allowed: 1
group_id: null
group_name: null
created: "2026-10-26 14:43:58"
modified: "2026-11-08 20:38:01"
- in_primary_domain: example.org
id: 20
domain: example.net
public_comment: ""
private_comment: ""
goto: null@localhost
address: "@example.net"
is_catch_all: 1
internal: 0
active: 1
active_int: 1
sogo_visible: 0
sogo_visible_int: 0
sender_allowed: 0
group_id: null
group_name: null
created: "2026-11-02 09:12:40"
modified: null
one:
summary: get/alias/12
value:
in_primary_domain: ""
id: 12
domain: example.org
public_comment: Sales team
private_comment: null
goto: anna@example.org,ben@example.org
address: sales@example.org
is_catch_all: 0
internal: 0
active: 1
active_int: 1
sogo_visible: 1
sogo_visible_int: 1
sender_allowed: 1
group_id: null
group_name: null
created: "2026-10-26 14:43:58"
modified: "2026-11-08 20:38:01"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/alias/all/{domains}:
get:
tags:
- Aliases
summary: Get the aliases of domains
operationId: getAliasesByDomain
description: >-
Lists the aliases of the named domains or alias domains, skipping
domains the caller does not manage. `{}` if there is none.
parameters:
- name: domains
in: path
required: true
description: Comma-separated domain names
schema:
type: string
example: example.org,example.net
responses:
"200":
description: The list of aliases
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Alias"
example:
- in_primary_domain: ""
id: 12
domain: example.org
public_comment: Sales team
private_comment: null
goto: anna@example.org,ben@example.org
address: sales@example.org
is_catch_all: 0
internal: 0
active: 1
active_int: 1
sogo_visible: 1
sogo_visible_int: 1
sender_allowed: 1
group_id: null
group_name: null
created: "2026-10-26 14:43:58"
modified: "2026-11-08 20:38:01"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/time_limited_aliases/{mailbox}:
get:
tags:
- Mailbox user settings
summary: Get the time-limited aliases of a mailbox
operationId: getTimeLimitedAliases
description: >-
The valid or permanent time-limited aliases of the mailbox. `{}` if
none or no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: List of aliases
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TimeLimitedAlias"
example:
- address: kahd.osuwe@example.org
goto: john.doe@example.org
description: Online shop registration
validity: 1795699200
created: "2026-11-10 09:00:00"
modified: null
permanent: 0
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/time_limited_alias:
post:
tags:
- Mailbox user settings
summary: Update time-limited aliases
operationId: editTimeLimitedAlias
description: >-
Sets a new expiry (`validity` hours from now) or makes the aliases
permanent. Needs the user ACL `spam_alias`. Without `validity` or a
true `permanent` nothing changes.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Alias address or list of addresses
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
validity:
type: [integer, string]
description: Hours from now until the alias expires (not range-checked); ends a permanent state
permanent:
type: [boolean, integer, string]
description: true makes the alias permanent (wins over `validity`)
example:
items:
- kahd.osuwe@example.org
attr:
validity: 24
permanent: 0
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/time_limited_alias:
post:
tags:
- Mailbox user settings
summary: Delete time-limited aliases
operationId: deleteTimeLimitedAlias
description: >-
Deletes time-limited aliases. Needs the user ACL `spam_alias`.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Alias addresses
items:
type: string
example:
- kahd.osuwe@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/pushover-test:
post:
tags:
- Mailbox user settings
summary: Verify the Pushover credentials of mailboxes
operationId: testPushover
description: >-
Checks the stored Pushover credentials of each mailbox with the
Pushover API; `attr` is not used. Same access as `edit/pushover`.
Answers "Pushover API OK (200): ..." or "Pushover API ERR (code): ...";
a mailbox without settings stops the call.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
description: Not used
example:
items:
- john.doe@example.org
attr: {}
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/delimiter_action:
post:
tags:
- Mailbox user settings
summary: Set the handling of tagged mail
operationId: editDelimiterAction
description: >-
Handling of mail to `user+tag@example.org`: move to the subfolder "tag"
(`subfolder`), add "[tag]" to the subject (`subject`) or nothing
(`none`, also for other values). Needs the user ACL `delimiter_action`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
properties:
tagged_mail_handler:
type: string
enum:
- subfolder
- subject
- none
example:
items:
- john.doe@example.org
attr:
tagged_mail_handler: subfolder
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/tls_policy:
post:
tags:
- Mailbox user settings
summary: Set the TLS policy of mailboxes
operationId: editTlsPolicy
description: >-
Enforces TLS for incoming and/or outgoing mail; fields not sent keep
their value. Needs the user ACL `tls_policy`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
properties:
tls_enforce_in:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: 1 accepts incoming mail only over TLS
tls_enforce_out:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: 1 sends outgoing mail only over TLS
example:
items:
- john.doe@example.org
attr:
tls_enforce_in: 1
tls_enforce_out: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/spam-score:
get:
tags:
- Mailbox user settings
summary: Get the default spam score
operationId: getDefaultSpamScore
description: >-
The spam thresholds of the session user; for API keys the Rspamd
default (`5,15` if Rspamd is unreachable).
responses:
"200":
description: Thresholds
content:
application/json:
schema:
$ref: "#/components/schemas/SpamScore"
example:
score: "8,15"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/api-key/{id}:
get:
summary: Get API key
description: One API key with its value. A read-only API key gets `{}`.
operationId: getApiKey
tags:
- API Keys
parameters:
- name: id
in: path
required: true
description: ID of the API key
schema:
type: integer
example: 3
responses:
"200":
description: The API key, `{}` if there is none with this ID or for a read-only API key
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
example:
id: 3
description: provisioning
access: rw
api_key: 1B7E2C-94F0A3-6D5B18-C2E7F4-03A9D6
allow_from:
- 192.0.2.10
- 2001:db8::/64
skip_ip_check: 0
service: 0
active: 1
created: "2026-11-02 09:12:44"
modified: "2026-11-05 16:40:02"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/api-key/all:
get:
summary: Get API keys
description: >-
Lists all API keys with their values, service keys first. A read-only
API key gets `{}`.
operationId: getApiKeys
tags:
- API Keys
responses:
"200":
description: The API keys, `{}` if there are none or for a read-only API key
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ApiKey"
example:
- id: 1
description: API_KEY
access: rw
api_key: 8F2D41-0C9A7B-5E3F12-AB46C0-77D1E9
allow_from:
- 192.0.2.0/24
skip_ip_check: 0
service: 1
active: 1
created: "2026-09-21 10:20:00"
modified: null
- id: 3
description: provisioning
access: rw
api_key: 1B7E2C-94F0A3-6D5B18-C2E7F4-03A9D6
allow_from:
- 192.0.2.10
- 2001:db8::/64
skip_ip_check: 0
service: 0
active: 1
created: "2026-11-02 09:12:44"
modified: "2026-11-05 16:40:02"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/app-passwd/all/{mailbox}:
get:
tags:
- App Passwords
summary: Get the app passwords of a mailbox
operationId: getAppPasswords
description: >-
The app passwords of the mailbox, with password hashes. `{}` if none or
no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: List of app passwords
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AppPassword"
example:
- id: 23
name: Thunderbird
mailbox: john.doe@example.org
domain: example.org
password: "{BLF-CRYPT}$2y$10$..."
created: "2026-11-08 20:38:01"
modified: null
imap_access: 1
smtp_access: 1
dav_access: 0
eas_access: 0
pop3_access: 0
sieve_access: 1
active: 1
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/app-passwd/all:
get:
tags:
- App Passwords
summary: Get the app passwords of the logged-in mailbox
operationId: getOwnAppPasswords
description: >-
The app passwords of the logged-in mailbox user. API keys get `{}`; use
`get/app-passwd/all/{mailbox}`.
responses:
"200":
description: List of app passwords
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AppPassword"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/app-passwd/{id}:
get:
tags:
- App Passwords
summary: Get an app password (broken)
operationId: getAppPassword
description: >-
Broken: always ends with an error and an empty body. Use
`get/app-passwd/all/{mailbox}`.
parameters:
- name: id
in: path
required: true
description: App password ID
schema:
type: integer
example: 23
responses:
"200":
description: Empty body
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/app-passwd:
post:
tags:
- App Passwords
summary: Update app passwords
operationId: editAppPassword
description: >-
Changes app passwords by ID; fields not sent keep their value. Needs
the user ACL `app_passwds`.
Messages: `object_modified`; errors `app_passwd_id_invalid`,
`password_complexity`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: App password ID or list of IDs
oneOf:
- type: integer
- type: array
items:
type: integer
attr:
type: object
properties:
username:
type: string
description: Mailbox the app passwords belong to (required for API keys)
app_name:
type: string
app_passwd:
type: string
format: password
description: New password; changed only together with `app_passwd2`
app_passwd2:
type: string
format: password
protocols:
description: Replaces the allowed protocols
type: array
items:
type: string
enum:
- imap_access
- smtp_access
- pop3_access
- sieve_access
- dav_access
- eas_access
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
example:
items:
- 23
attr:
username: john.doe@example.org
active: 0
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/bcc/{id}:
get:
tags:
- Address Rewriting
summary: Get BCC maps
operationId: getBccMaps
description: >-
`all` lists the BCC maps of the domains the caller manages, an ID
returns one map with an extra member `"0": null`. `{}` if there is
none.
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a BCC map"
schema:
type: string
example: all
responses:
"200":
description: The list of BCC maps (`all`) or one BCC map
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/BccMap"
- $ref: "#/components/schemas/BccMap"
examples:
all:
summary: get/bcc/all
value:
- id: 3
local_dest: "@example.org"
bcc_dest: archive@example.com
active: 1
type: rcpt
created: "2026-11-03 10:15:22"
domain: example.org
modified: null
one:
summary: get/bcc/3
value:
id: 3
local_dest: "@example.org"
bcc_dest: archive@example.com
active: 1
type: rcpt
created: "2026-11-03 10:15:22"
domain: example.org
modified: null
"0": null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/dkim/{domain}:
get:
summary: Get the DKIM key of a domain
description: >-
The DKIM public key of a domain or alias domain and the TXT record for
`<selector>._domainkey.<domain>`. `privkey` is empty unless
`SHOW_DKIM_PRIV_KEYS` is enabled.
operationId: getDkimKey
tags:
- DKIM
parameters:
- name: domain
in: path
required: true
description: Domain or alias domain name
schema:
type: string
example: example.org
responses:
"200":
description: The DKIM key
content:
application/json:
schema:
$ref: "#/components/schemas/DkimKey"
example:
pubkey: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxV3...IDAQAB
length: "2048"
dkim_txt: v=DKIM1;k=rsa;t=s;s=email;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxV3...IDAQAB
dkim_selector: dkim
privkey: ""
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/dkim_import:
post:
summary: Import a DKIM key
description: >-
Imports an RSA private key as the DKIM key of a domain, which need not
exist in mailcow. Success answers `dkim_removed` and `dkim_added`.
Messages: errors `private_key_error`, `dkim_domain_or_sel_exists`.
operationId: importDkimKey
tags:
- DKIM
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- private_key_file
properties:
domain:
type: string
description: Domain name
dkim_selector:
type: string
default: dkim
description: Selector (letters, digits, `-`, `_`, `.`)
private_key_file:
type: string
description: The private key in PEM format (the text, not a file upload)
overwrite_existing:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Replace an existing key of the domain
example:
domain: example.org
dkim_selector: dkim2026
private_key_file: "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----"
overwrite_existing: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/domain-admin/all:
get:
summary: Get domain administrators
description: Lists all domain administrators.
operationId: getDomainAdmins
tags:
- Domain admin
responses:
"200":
description: The domain administrators, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DomainAdmin"
example:
- username: domainadmin1
tfa_active: 0
tfa_active_int: 0
active: 1
active_int: 1
created: "2026-09-21 10:24:48"
attributes:
force_tfa: "0"
force_pw_update: "0"
selected_domains:
- example.org
unselected_domains:
- example.com
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/domain-admin/{username}:
get:
summary: Get domain administrator
description: Details of one domain administrator.
operationId: getDomainAdmin
tags:
- Domain admin
parameters:
- name: username
in: path
required: true
description: Username of the domain administrator
schema:
type: string
example: domainadmin1
responses:
"200":
description: The domain administrator, `{}` if there is none of this name
content:
application/json:
schema:
$ref: "#/components/schemas/DomainAdmin"
example:
username: domainadmin1
tfa_active: 0
tfa_active_int: 0
active: 1
active_int: 1
created: "2026-09-21 10:24:48"
attributes:
force_tfa: "0"
force_pw_update: "0"
selected_domains:
- example.org
- example.com
unselected_domains: ""
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/domain/{id}:
get:
summary: Get domains
description: >-
`all` lists all domains (`{}` if none), a domain name returns that
domain, an alias domain name its target. Domain admins see only their
domains. Quotas are in bytes.
operationId: getDomains
tags:
- Domains
parameters:
- name: id
in: path
required: true
description: "`all` or a domain name"
schema:
type: string
example: all
- name: tags
in: query
required: false
description: >-
Only with `all`: comma-separated tag names, answers only the domains
with a tag that contains one of them
schema:
type: string
example: customer,premium
responses:
"200":
description: The list of domains (`all`) or one domain
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: "#/components/schemas/Domain"
- $ref: "#/components/schemas/Domain"
example:
- max_new_mailbox_quota: 10632560640
def_new_mailbox_quota: 3221225472
quota_used_in_domain: "104857600"
bytes_total: "79324302"
msgs_total: "132"
mboxes_in_domain: 3
mboxes_left: 7
domain_name: example.org
domain_h_name: example.org
description: Example Org
max_num_aliases_for_domain: 400
max_num_mboxes_for_domain: 10
def_quota_for_mbox: 3221225472
max_quota_for_mbox: 10737418240
max_quota_for_domain: 10737418240
relayhost: "0"
backupmx: 0
backupmx_int: 0
gal: 1
gal_int: 1
rl:
value: "100"
frame: h
active: 1
active_int: 1
relay_all_recipients: 0
relay_all_recipients_int: 0
relay_unknown_only: 0
relay_unknown_only_int: 0
created: "2026-09-21 10:24:34"
modified: "2026-11-06 18:15:08"
aliases_in_domain: 1
aliases_left: 399
domain_admins: anna.admin
tags:
- customer
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/domain/template/{id}:
get:
summary: Get domain templates
description: >-
`all` lists the domain templates, an ID returns that template. Domain
admins may call it too. Quotas are in bytes.
operationId: getDomainTemplates
tags:
- Domains
parameters:
- name: id
in: path
required: true
description: "`all` or a template ID"
schema:
type: string
example: all
responses:
"200":
description: The list of templates (`all`) or one template
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: "#/components/schemas/DomainTemplate"
- $ref: "#/components/schemas/DomainTemplate"
example:
- id: 1
template: Default
type: domain
attributes:
tags: []
max_num_aliases_for_domain: 400
max_num_mboxes_for_domain: 10
def_quota_for_mbox: 3221225472
max_quota_for_mbox: 10737418240
max_quota_for_domain: 10737418240
rl_frame: s
rl_value: ""
active: 1
gal: 1
backupmx: 0
relay_all_recipients: 0
relay_unknown_only: 0
dkim_selector: dkim
key_size: 2048
created: "2026-09-21 10:23:08"
modified: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/domain/template:
post:
summary: Add a domain template
description: >-
Adds a domain template (defaults for new domains). Quotas are sent in
MiB, returned in bytes. Fields not sent, and numbers and quotas sent as
0, get the defaults shown.
Messages: `template_added`; errors `template_name_invalid`,
`template_exists`.
operationId: addDomainTemplate
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/DomainTemplateInput"
- required:
- template
example:
template: Small business
max_num_aliases_for_domain: 400
max_num_mboxes_for_domain: 25
def_quota_for_mbox: 2048
max_quota_for_mbox: 5120
max_quota_for_domain: 51200
rl_value: 500
rl_frame: h
active: 1
gal: 1
backupmx: 0
relay_all_recipients: 0
relay_unknown_only: 0
dkim_selector: dkim
key_size: 2048
tags:
- small
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/domain/template:
post:
summary: Edit domain templates
description: >-
Replaces domain templates. Fields not sent are reset: numbers and quotas
to 0, the rest to the defaults shown. Edit one template per call, with
several IDs all get the first one's name. Always answers
`template_modified`, also for unknown IDs.
operationId: editDomainTemplate
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Template ID or list of template IDs
oneOf:
- type: [integer, string]
- type: array
items:
type: [integer, string]
attr:
$ref: "#/components/schemas/DomainTemplateInput"
example:
items:
- 2
attr:
template: Small business
max_num_aliases_for_domain: 400
max_num_mboxes_for_domain: 50
def_quota_for_mbox: 2048
max_quota_for_mbox: 5120
max_quota_for_domain: 102400
rl_value: 500
rl_frame: h
active: 1
gal: 1
backupmx: 0
relay_all_recipients: 0
relay_unknown_only: 0
dkim_selector: dkim
key_size: 2048
tags:
- small
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/domain/template:
post:
summary: Delete a domain template
description: >-
Deletes a domain template; only the first ID of the list is used. The
`Default` template cannot be deleted. Always answers
`template_removed`.
operationId: deleteDomainTemplate
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Template IDs (only the first is used)
items:
type: [integer, string]
example:
- 2
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/search/domain:
post:
summary: Search domains (table of the UI)
description: >-
Paging, sorting and searching for the DataTables domain table of the UI.
Read-only API keys may use it, domain admins see only their domains.
Positions in `columns` and `order[].column`: 2 domain name, 3 aliases,
4 mailboxes, 5 domain quota, 6 storage (sort only), 7 default mailbox
quota, 8 max. mailbox quota, 10 relay domain, 14 tags (global search
only), 15 active; others mean the domain name. `columns` is required
with `search.value`.
Without `Content-Type: application/json` all domains are returned. SQL
errors answer `{"error": "..."}` with status 200.
operationId: searchDomains
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DomainSearchRequest"
example:
draw: 1
start: 0
length: 10
search:
value: example
order:
- column: 2
dir: asc
columns:
- data: ""
searchable: false
orderable: false
- data: chkbox
searchable: false
orderable: false
- data: domain_h_name
searchable: true
orderable: true
search:
value: ""
responses:
"200":
description: One page of domains, with the counts DataTables needs
content:
application/json:
schema:
$ref: "#/components/schemas/DomainSearchResult"
example:
draw: 1
recordsTotal: 12
recordsFiltered: 1
data:
- max_new_mailbox_quota: 10632560640
def_new_mailbox_quota: 3221225472
quota_used_in_domain: "104857600"
bytes_total: "79324302"
msgs_total: "132"
mboxes_in_domain: 3
mboxes_left: 7
domain_name: example.org
domain_h_name: example.org
description: Example Org
max_num_aliases_for_domain: 400
max_num_mboxes_for_domain: 10
def_quota_for_mbox: 3221225472
max_quota_for_mbox: 10737418240
max_quota_for_domain: 10737418240
relayhost: "0"
backupmx: 0
backupmx_int: 0
gal: 1
gal_int: 1
rl: false
active: 1
active_int: 1
relay_all_recipients: 0
relay_all_recipients_int: 0
relay_unknown_only: 0
relay_unknown_only_int: 0
created: "2026-09-21 10:24:34"
modified: "2026-11-06 18:15:08"
aliases_in_domain: 1
aliases_left: 399
domain_admins: "-"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/alias-domain/{id}:
get:
summary: Get alias domains
description: >-
`all` lists all alias domains, a name returns that alias domain. Domain
admins see only those of their domains.
operationId: getAliasDomains
tags:
- Domains
parameters:
- name: id
in: path
required: true
description: "`all` or an alias domain name"
schema:
type: string
example: all
responses:
"200":
description: The list of alias domains (`all`) or one alias domain
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: "#/components/schemas/AliasDomain"
- $ref: "#/components/schemas/AliasDomain"
example:
- alias_domain: example.net
parent_is_backupmx: 0
target_domain: example.org
active: 1
active_int: 1
rl: false
created: "2026-10-02 08:12:45"
modified: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/alias-domain:
post:
summary: Add alias domains
description: >-
Adds alias domains: mail goes to the same local part in the target
domain, which must be accessible and no relay domain. Needs the ACL
`alias_domains`. Can also set the rate limit and create a DKIM key. An
invalid name ends the call without an answer.
Messages: `aliasd_added`; errors `alias_domain_invalid`,
`targetd_not_found`, `targetd_relay_domain`.
operationId: addAliasDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- alias_domain
- target_domain
properties:
alias_domain:
type: string
description: >-
Alias domain name; several are separated by spaces, commas,
semicolons or line breaks
target_domain:
type: string
description: The domain the alias domain points to
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Alias domain active (inactive when not sent)
rl_value:
type: [integer, string]
description: Rate limit, messages per `rl_frame`; empty or 0 = none
rl_frame:
type: string
enum: [s, m, h, d]
description: Rate limit time frame
dkim_selector:
type: string
description: Selector of the DKIM key that is created
key_size:
type: [integer, string]
description: >-
RSA size of the new DKIM key in bits; a key needs
`key_size` and `dkim_selector`
example:
alias_domain: example.net
target_domain: example.org
active: 1
rl_value: 100
rl_frame: h
dkim_selector: dkim
key_size: 2048
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/alias-domain:
post:
summary: Edit alias domains
description: >-
Changes alias domains; fields not sent keep their value. The new target
must be an accessible domain, not an alias domain.
Messages: `aliasd_modified`; errors `alias_domain_invalid`,
`target_domain_invalid`.
operationId: editAliasDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Alias domain name or list of alias domain names
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Alias domain active
target_domain:
type: string
description: New target domain
example:
items:
- example.net
attr:
active: 1
target_domain: example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/alias-domain:
post:
summary: Delete alias domains
description: >-
Deletes alias domains with their aliases, spam aliases and BCC maps.
The rate limit is kept.
Messages: `alias_domain_removed`; error `domain_invalid`.
operationId: deleteAliasDomain
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Alias domain names
items:
type: string
example:
- example.net
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/mta-sts:
post:
summary: Add an MTA-STS policy
description: >-
Adds the MTA-STS policy of a domain, published when active at
`https://mta-sts.<domain>/.well-known/mta-sts.txt`. The `_mta-sts` TXT
record ID is the change time (`YYYYMMDDhhmmss`). Policies of alias
domains are never published, they use their target's. A second policy
fails with a database error. There is no read route.
Messages: errors `version_invalid`, `mode_invalid`, `max_age_invalid`,
`mx_invalid`.
operationId: addMtaSts
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- version
- mode
- mx
- max_age
properties:
domain:
type: string
description: Domain or alias domain
version:
type: string
enum: [stsv1, STSv1]
description: Policy version (case-insensitive)
mode:
type: string
enum: [enforce, testing, none]
description: >-
`enforce` rejects delivery without valid TLS, `testing`
only reports, `none` publishes without effect
mx:
type: string
description: Comma-separated MX host names, wildcards like `*.example.org` allowed
max_age:
type: [integer, string]
description: Seconds senders may cache the policy, 1 to 31536000
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: Policy published (inactive when not sent)
example:
domain: example.org
version: stsv1
mode: enforce
mx: mail.example.org,mx2.example.org
max_age: 86400
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mta-sts:
post:
summary: Edit MTA-STS policies
description: >-
Changes MTA-STS policies; fields not sent keep their value, but
`version` is required. Changing `version`, `mode`, `mx` or `max_age`
gives a new policy ID. A domain without policy answers `access_denied`.
Messages: `object_modified`; errors `version_invalid`, `mode_invalid`,
`mx_invalid`.
operationId: editMtaSts
tags:
- Domains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Domain name or list of domain names
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
required:
- version
properties:
version:
type: string
enum: [stsv1, STSv1]
description: Policy version
mode:
type: string
enum: [enforce, testing, none]
description: Policy mode
mx:
type: string
description: Comma-separated MX host names
max_age:
type: [integer, string]
description: Seconds senders may cache the policy, 1 to 31557600
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
description: Policy published
example:
items:
- example.org
attr:
version: stsv1
mode: testing
mx: mail.example.org
max_age: 604800
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/fail2ban:
get:
summary: Get Fail2Ban settings and bans
description: >-
Returns the Fail2Ban settings, regex filters, allow- and denylists and
the current bans.
operationId: getFail2Ban
tags:
- Fail2Ban
responses:
"200":
description: Settings and bans
content:
application/json:
schema:
$ref: "#/components/schemas/Fail2Ban"
example:
ban_time: 1800
ban_time_increment: true
max_ban_time: 86400
netban_ipv4: 32
netban_ipv6: 128
max_attempts: 10
retry_window: 600
banlist_id: a2c11baf-5770-47de-9c5e-575bd7bc9218
manage_external: 0
regex:
"1": "^mailcow UI: Invalid password for .+ by ([0-9a-f\\.:]+)$"
"2": "^Rspamd UI: Invalid password by ([0-9a-f\\.:]+)$"
whitelist: |-
192.0.2.0/24
mail.example.org
blacklist: 198.51.100.66/32
perm_bans:
- network: 198.51.100.66/32
ip: 198.51.100.66
active_bans:
- queued_for_unban: 0
network: 203.0.113.7/32
ip: 203.0.113.7
banned_until: 00h 27m 08s
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/fail2ban/banlist:
post:
summary: Renew the Fail2Ban banlist URL
description: >-
Gives the banlist URL `/f2b-banlist?id=<banlist_id>` a new random ID;
the old URL stops working. `items` must hold the current `banlist_id`,
else the status is 404. A Redis error gives status 500.
Messages: `f2b_banlist_refreshed`; errors `redis_error`.
operationId: refreshFail2BanBanlist
tags:
- Fail2Ban
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: The current banlist ID (single value or a list with it as first element)
oneOf:
- type: array
items:
type: string
- type: string
attr:
type: object
description: Not used
required:
- items
example:
items:
- a2c11baf-5770-47de-9c5e-575bd7bc9218
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
description: "`items` does not hold the current banlist ID"
content:
application/json:
schema:
$ref: "#/components/schemas/TaskResult"
example:
type: error
msg: Cannot edit item
/api/v1/get/logs/acme/{count}:
get:
summary: Get ACME logs (count or range)
description: Entries of the ACME (Let's Encrypt) log, newest first.
operationId: getAcmeLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/AcmeLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/api/{count}:
get:
summary: Get API logs (count or range)
description: API requests with their data (secrets replaced by `*`), newest first.
operationId: getApiLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/ApiLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/autodiscover/{count}:
get:
summary: Get Autodiscover logs (count or range)
description: Autodiscover requests (Outlook, ActiveSync) with the offered service, newest first.
operationId: getAutodiscoverLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/AutodiscoverLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/dovecot/{count}:
get:
summary: Get Dovecot logs (count or range)
description: Entries of the Dovecot log (IMAP, POP3, Sieve, LMTP), newest first.
operationId: getDovecotLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/DovecotLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/netfilter/{count}:
get:
summary: Get netfilter logs (count or range)
description: Entries of netfilter (failed logins, bans), newest first.
operationId: getNetfilterLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/NetfilterLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/postfix/{count}:
get:
summary: Get Postfix logs (count or range)
description: Entries of the Postfix log (SMTP), newest first.
operationId: getPostfixLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/PostfixLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/ratelimited/{count}:
get:
summary: Get rate limit logs (count or range)
description: Messages rejected by a rate limit, newest first.
operationId: getRatelimitLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/RatelimitLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/rspamd-history/{count}:
get:
summary: Get Rspamd history (count or range)
description: Messages scanned by Rspamd, newest first.
operationId: getRspamdHistoryByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: >-
`N`: the newest N messages; `from-to` (from ≥ 1) counts from 0, so
`2-3` gives the third and fourth newest
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/RspamdHistory"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/sogo/{count}:
get:
summary: Get SOGo logs (count or range)
description: Entries of the SOGo log, newest first.
operationId: getSogoLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/SogoLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/watchdog/{count}:
get:
summary: Get watchdog logs (count or range)
description: Watchdog health checks, newest first.
operationId: getWatchdogLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/WatchdogLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/acme:
get:
summary: Get ACME logs
description: The newest 1000 entries of the ACME (Let's Encrypt) log, newest first.
operationId: getAcmeLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/AcmeLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/api:
get:
summary: Get API logs
description: >-
The newest 1000 API requests with their data (secrets replaced by
`*`), newest first.
operationId: getApiLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/ApiLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/autodiscover:
get:
summary: Get Autodiscover logs
description: >-
The newest 1000 Autodiscover requests (Outlook, ActiveSync) with the
offered service, newest first.
operationId: getAutodiscoverLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/AutodiscoverLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/cron:
get:
summary: Get cron logs
description: >-
The newest 1000 entries of the mailcow scheduled tasks (identity
provider sync, group shares, ...), newest first.
operationId: getCronLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/CronLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/cron/{count}:
get:
summary: Get cron logs (count or range)
description: Entries of the mailcow scheduled tasks, newest first.
operationId: getCronLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: "`N`: the newest N entries; `from-to`: entries `from` to `to` (newest = 1)"
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/CronLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/dovecot:
get:
summary: Get Dovecot logs
description: The newest 1000 entries of the Dovecot log (IMAP, POP3, Sieve, LMTP), newest first.
operationId: getDovecotLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/DovecotLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/netfilter:
get:
summary: Get netfilter logs
description: The newest 1000 entries of netfilter (failed logins, bans), newest first.
operationId: getNetfilterLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/NetfilterLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/postfix:
get:
summary: Get Postfix logs
description: The newest 1000 entries of the Postfix log (SMTP), newest first.
operationId: getPostfixLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/PostfixLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/ratelimited:
get:
summary: Get rate limit logs
description: The newest 1000 messages rejected by a rate limit, newest first.
operationId: getRatelimitLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/RatelimitLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/rspamd-history:
get:
summary: Get Rspamd history
description: The newest 1000 messages scanned by Rspamd, newest first.
operationId: getRspamdHistory
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/RspamdHistory"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/rspamd-stats:
get:
summary: Get Rspamd statistics
description: Rspamd statistics (scanned and learned messages, actions, Bayes).
operationId: getRspamdStats
tags:
- Logs
responses:
"200":
description: The statistics, `{}` if Rspamd cannot be reached
content:
application/json:
schema:
$ref: "#/components/schemas/RspamdStats"
example:
version: 3.12.1
config_id: ch8ha1o68oxb3xf9izngisz4wxuxgs86n9gg6yko7jtt4msu4bxhuunnoi4pk7an4y5htzjb1y9nwsxmkjhdu671ocb5b5ea1g38csb
uptime: 25891
read_only: false
scanned: 300
learned: 30
actions:
reject: 38
soft reject: 0
rewrite subject: 0
add header: 6
greylist: 1
no action: 255
scan_times:
- 0.340365
- 0.48114
spam_count: 44
ham_count: 256
connections: 24
control_connections: 700
total_learns: 29
statfiles:
- revision: 6
users: 1
used: 0
total: 0
size: 0
symbol: BAYES_SPAM
type: redis
languages: 0
class: spam
fuzzy_hashes:
mailcow: 0
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/sasl:
get:
summary: Get SASL logs
description: >-
The newest 1000 successful logins (IMAP, POP3, SMTP, SOGo, ...), one
entry per service, address and user, newest first.
operationId: getSaslLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/SaslLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/sasl/{count}:
get:
summary: Get SASL logs (count or range)
description: >-
Successful logins, one entry per service, address and user, newest
first.
operationId: getSaslLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: >-
`N`: the newest N entries; `from-to`: `to` entries starting at
`from` (newest = 1), so `2-3` gives entries 2 to 4
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/SaslLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/sogo:
get:
summary: Get SOGo logs
description: The newest 1000 entries of the SOGo log, newest first.
operationId: getSogoLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/SogoLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/ui:
get:
summary: Get mailcow UI logs
description: The newest 1000 messages of UI and API calls, newest first.
operationId: getUiLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/UiLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/ui/{count}:
get:
summary: Get mailcow UI logs (count or range)
description: Messages of UI and API calls, newest first.
operationId: getUiLogsByCount
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: >-
`N`: the newest N entries; `from-to`: `to` entries starting at
`from` (newest = 1), so `2-3` gives entries 2 to 4
schema:
type: string
pattern: ^[0-9]+(-[0-9]+)?$
example: "50"
responses:
"200":
$ref: "#/components/responses/UiLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/logs/watchdog:
get:
summary: Get watchdog logs
description: The newest 1000 watchdog health checks, newest first.
operationId: getWatchdogLogs
tags:
- Logs
responses:
"200":
$ref: "#/components/responses/WatchdogLogs"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/{id}:
get:
tags:
- Mailboxes
summary: Get a mailbox
operationId: getMailbox
description: >-
One mailbox, `{}` if not found or no access. A mailbox user may read
its own.
With `tags`, `{id}` is a search term: the answer lists the mailboxes
whose address contains `{id}` and that have a matching tag.
parameters:
- name: id
in: path
required: true
description: "Mailbox address (with `tags`: part of the address, e.g. a domain)"
schema:
type: string
example: john.doe@example.org
- $ref: "#/components/parameters/MailboxTagsQuery"
responses:
"200":
description: The mailbox; with `tags` a list of mailboxes
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Mailbox"
- type: array
items:
$ref: "#/components/schemas/Mailbox"
examples:
mailbox:
$ref: "#/components/examples/MailboxDetails"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox-group/{id}:
get:
summary: Get mailbox group
description: >-
One group by id, visible as in `GET /api/v1/get/mailbox-group/all`.
operationId: getMailboxGroup
tags:
- Groups
parameters:
- name: id
in: path
required: true
description: Group id
schema:
type: integer
example: 7
responses:
"200":
description: The group
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxGroup"
example:
id: 7
domain: example.org
name: Sales
description: Sales team
address: sales@example.org
sender_allowed: 1
sogo_visible: 0
internal: 1
template_id: 3
template: Staff
priority: 10
idp_ref: null
members:
- username: alice@example.org
source: manual
send_as:
- "@example.com"
imap_grants: []
sogo_grants: []
active: 1
created: "2026-10-25 12:00:00"
modified: null
can_edit: true
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox-group/member/{username}:
get:
summary: Get group memberships of a mailbox
description: >-
The groups of a mailbox with its effective template and send-as
addresses. Domain admins with the `mailbox_groups` ACL may read their
mailboxes and see only groups of their domains; users may read their
own.
operationId: getMailboxGroupMemberships
tags:
- Groups
parameters:
- name: username
in: path
required: true
description: Mailbox (case-insensitive)
schema:
type: string
example: alice@example.org
responses:
"200":
description: The memberships
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxGroupMemberships"
example:
groups:
- id: 7
domain: example.org
name: Sales
address: sales@example.org
sender_allowed: 1
active: 1
priority: 10
template: Staff
source: manual
template: Staff
send_as:
- orders@example.org
- sales@example.org
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox-group/all:
get:
summary: Get mailbox groups
description: >-
All groups the caller may see, ordered by domain and name. Domain admins
with the `mailbox_groups` ACL get the groups of their domains.
operationId: getMailboxGroups
tags:
- Groups
responses:
"200":
description: The groups
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/MailboxGroup"
example:
- id: 7
domain: example.org
name: Sales
description: Sales team
address: sales@example.org
sender_allowed: 1
sogo_visible: 0
internal: 0
template_id: 3
template: Staff
priority: 10
idp_ref: null
members:
- username: alice@example.org
source: manual
- username: bob@example.org
source: idp
send_as:
- orders@example.org
imap_grants:
- owner: shared@example.org
rights: write
subscribe: 1
state: applied
last_error: null
sogo_grants:
- owner: shared@example.org
type: Calendar
folder: personal
access: read
subscribe: 0
state: pending
last_error: null
active: 1
created: "2026-10-25 12:00:00"
modified: "2026-10-28 09:14:03"
can_edit: true
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox-group/all/{domains}:
get:
summary: Get mailbox groups of domains
description: >-
Like `GET /api/v1/get/mailbox-group/all`, limited to the given domains.
operationId: getMailboxGroupsOfDomains
tags:
- Groups
parameters:
- name: domains
in: path
required: true
description: One domain or a comma-separated list of domains
schema:
type: string
example: example.org,example.com
responses:
"200":
description: The groups of the domains
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/MailboxGroup"
example:
- id: 7
domain: example.org
name: Sales
description: ""
address: sales@example.org
sender_allowed: 1
sogo_visible: 1
internal: 0
template_id: null
template: null
priority: 0
idp_ref: null
members:
- username: alice@example.org
source: manual
send_as: []
imap_grants: []
sogo_grants: []
active: 1
created: "2026-10-25 12:00:00"
modified: null
can_edit: true
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/identity-provider/sync-status:
get:
summary: Get identity sync status
description: >-
Status of the identity sync: provider, mailbox counts and the last 10
runs. Runs with status `blocked` (stopped by `offboarding_limit`) or
`error` changed nothing.
operationId: getIdentitySyncStatus
tags:
- Identity Provider
responses:
"200":
description: The sync status
content:
application/json:
schema:
$ref: "#/components/schemas/IdentitySyncStatus"
example:
provider: keycloak
can_sync: true
sync_enabled: true
counts:
accounts: 120
linked: 118
idp_disabled: 2
missing: 1
runs:
- id: 42
provider: keycloak
mode: run
status: ok
requested_by: ""
created: "2026-11-09 12:00:00"
started: "2026-11-09 12:00:01"
finished: "2026-11-09 12:00:03"
summary:
counts:
links: 0
creates: 1
deactivate: 1
restore: 0
release: 0
missing: 1
found: 0
updates: 3
group_creates: 0
group_renames: 0
memberships: 2
orphaned_groups: 0
conflicts: 0
membership_removals: 0
skipped: 0
errors: 0
details:
creates:
- new.user@example.org
deactivate:
- left.user@example.org
restore: []
missing:
- left.user@example.org
group_creates: []
conflicts: []
blocked: false
errors: []
mode: run
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/identity-link/{username}:
get:
summary: Get identity link of a mailbox
description: >-
The Identity Provider user a mailbox is linked to. Domain admins may
read their mailboxes. A never linked mailbox that the sync misses at the
provider has `missing_since` but no `external_id`.
operationId: getIdentityLink
tags:
- Identity Provider
parameters:
- name: username
in: path
required: true
description: Mailbox (case-insensitive)
schema:
type: string
example: alice@example.org
responses:
"200":
description: The link
content:
application/json:
schema:
$ref: "#/components/schemas/IdentityLink"
example:
provider: keycloak
external_id: 8d5da28d-7541-428b-8356-a9704f73e7f4
idp_disabled: 0
missing_since: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailq/all:
get:
summary: Get the mail queue
description: >-
Returns the Postfix mail queue, at most 10000 entries.
operationId: getMailQueue
tags:
- Queue Manager
responses:
"200":
description: List of queued messages
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/MailQueueItem"
example:
- queue_name: deferred
queue_id: B98C6260CA1
arrival_time: 1762768034
message_size: 1848
forced_expire: false
sender: sender@example.org
recipients:
- "rcpt@example.com (connect to mx.example.com[192.0.2.25]:25: Connection timed out)"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/postcat/{qid}:
get:
summary: Get a queued message
description: >-
Returns a queued message as postcat prints it: envelope, headers and
body. The answer is plain text despite the JSON content type. An
unknown queue ID gives the error text of postcat.
operationId: getQueuedMessage
tags:
- Queue Manager
parameters:
- name: qid
in: path
required: true
description: Postfix queue ID
schema:
type: string
example: B98C6260CA1
responses:
"200":
description: The postcat output as plain text (despite the JSON content type)
content:
application/json:
schema:
type: string
example: |
*** ENVELOPE RECORDS deferred/B/B98C6260CA1 ***
message_size: 1848 612 1 0 1848 0
message_arrival_time: Mon Nov 10 09:47:14 2026
create_time: Mon Nov 10 09:47:14 2026
named_attribute: rewrite_context=local
sender: sender@example.org
*** MESSAGE CONTENTS deferred/B/B98C6260CA1 ***
From: Sender <sender@example.org>
To: rcpt@example.com
Subject: Test
Hello
*** HEADER EXTRACTED deferred/B/B98C6260CA1 ***
original_recipient: rcpt@example.com
recipient: rcpt@example.com
*** MESSAGE FILE END deferred/B/B98C6260CA1 ***
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/oauth2-client/{id}:
get:
summary: Get OAuth2 client
description: One OAuth2 client with its secret.
operationId: getOAuth2Client
tags:
- oAuth Clients
parameters:
- name: id
in: path
required: true
description: ID of the client (`id`, not `client_id`)
schema:
type: integer
example: 1
responses:
"200":
description: The client, `{}` if there is none with this ID
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Client"
example:
id: 1
client_id: 17c76aaa88c0
client_secret: 73fc668a88147e32a31ff80c
redirect_uri: https://app.example.org/oauth/callback
grant_types: null
scope: profile
user_id: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/oauth2-client/all:
get:
summary: Get OAuth2 clients
description: >-
Lists the clients of the mailcow OAuth2 server with their secrets.
operationId: getOAuth2Clients
tags:
- oAuth Clients
responses:
"200":
description: The clients, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/OAuth2Client"
example:
- id: 1
client_id: 17c76aaa88c0
client_secret: 73fc668a88147e32a31ff80c
redirect_uri: https://app.example.org/oauth/callback
grant_types: null
scope: profile
user_id: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/oauth2-client:
post:
summary: Edit OAuth2 clients
description: >-
Per client, `revoke_tokens` deletes its tokens, else `renew_secret`
sets a new secret, else `redirect_uri` is changed. The first two act
whenever present, even with value 0.
Messages: `object_modified`; error `Redirect/Callback URL cannot be
empty`.
operationId: editOAuth2Client
tags:
- oAuth Clients
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
description: ID of the client, or a list of IDs
oneOf:
- type: [integer, string]
- type: array
items:
type: [integer, string]
attr:
type: object
properties:
redirect_uri:
type: string
description: New redirect URL; empty or missing keeps the current one
revoke_tokens:
type: [integer, string, boolean]
description: Present = delete the access and refresh tokens of the client
renew_secret:
type: [integer, string, boolean]
description: Present = generate a new client secret
required:
- items
- attr
example:
items:
- 1
attr:
redirect_uri: https://app.example.org/oauth/callback2
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/policy_bl_domain/{domain}:
get:
summary: Get the sender deny list of a domain
description: >-
The deny list (blacklist) entries of the domain and all its mailboxes;
`object` tells which.
operationId: getDomainBlacklist
tags:
- Domain antispam policies
parameters:
- name: domain
in: path
required: true
description: Domain name
schema:
type: string
example: example.org
responses:
"200":
description: The deny list entries
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DomainPolicyEntry"
example:
- object: example.org
value: "*@spam.example.com"
prefid: 13
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/policy_wl_domain/{domain}:
get:
summary: Get the sender allow list of a domain
description: >-
The allow list (whitelist) entries of the domain and all its
mailboxes; `object` tells which.
operationId: getDomainWhitelist
tags:
- Domain antispam policies
parameters:
- name: domain
in: path
required: true
description: Domain name
schema:
type: string
example: example.org
responses:
"200":
description: The allow list entries
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DomainPolicyEntry"
example:
- object: example.org
value: "*@partner.example.com"
prefid: 12
- object: anna@example.org
value: newsletter@example.net
prefid: 15
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/quarantine/all:
get:
summary: Get quarantined messages
description: >-
Returns the quarantined messages without content. Admins get every
item, domain admins those of their domains, mailbox users their own.
operationId: getQuarantine
tags:
- Quarantine
responses:
"200":
description: List of quarantine items
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/QuarantineItem"
example:
- id: 33
qid: 8224615004C1
subject: You have won
virus_flag: 0
score: 15.48
rcpt: john.doe@example.org
sender: bounces@send.example.com
action: reject
created: 1762768034
notified: 1
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/quarantine_category:
post:
tags:
- Quarantine
summary: Set the quarantine notification category of mailboxes
operationId: editQuarantineCategory
description: >-
Which quarantined mail the notifications list: rejected (`reject`),
sent to junk (`add_header`) or both (`all`). Needs the user ACL
`quarantine_category`; a mailbox user may change only its own. An
invalid value answers `access_denied`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
required:
- quarantine_category
properties:
quarantine_category:
type: string
enum:
- reject
- add_header
- all
example:
items:
- john.doe@example.org
attr:
quarantine_category: all
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/quarantine/{id}:
get:
summary: Get a quarantined message
description: >-
Returns one quarantine item with the raw message and the Rspamd
symbols. Domain admins and mailbox users only get their own items.
`[]` for an unknown ID.
operationId: getQuarantineItem
tags:
- Quarantine
parameters:
- name: id
in: path
required: true
description: ID of the quarantine item
schema:
type: string
example: "33"
responses:
"200":
description: The quarantine item
content:
application/json:
schema:
$ref: "#/components/schemas/QuarantineItemDetails"
example:
id: 33
qid: 8224615004C1
subject: You have won
score: 15.48
ip: 198.51.100.23
action: reject
symbols: '[{"name":"BAYES_SPAM","score":5.1,"options":["99.99%"]},{"name":"RBL_SPAMHAUS_SBL","score":4.0}]'
fuzzy_hashes: "[]"
sender: bounces@send.example.com
rcpt: john.doe@example.org
msg: "Return-Path: <bounces@send.example.com>\r\nFrom: Prize <bounces@send.example.com>\r\nTo: john.doe@example.org\r\nSubject: You have won\r\n\r\nClick here\r\n"
domain: null
notified: 1
created: "2026-11-10 09:47:14"
user: unknown
qhash: 3f9d8c0b2a4e6f1d7c5b9a8e0f2d4c6b8a1e3f5d7c9b0a2e4f6d8c1b3a5e7f9d
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/quarantine:
post:
summary: Edit quarantine settings
description: >-
Saves the global quarantine settings. Fields not sent are reset; a
missing `retention_size` or `max_size` turns the quarantine off. The
current values cannot be read through the API.
Messages: `saved_settings`; errors `redis_error`.
operationId: editQuarantineSettings
tags:
- Quarantine
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: Ignored
attr:
type: object
properties:
action:
type: string
const: settings
retention_size:
type: [integer, string]
description: Items kept per mailbox; 0 disables the quarantine
max_size:
type: [integer, string]
description: Maximum size in MiB of a quarantined message; 0 disables the quarantine
max_score:
type: [number, string]
description: No notification for messages with a higher spam score; empty = no limit
max_age:
type: [integer, string]
description: Days an item is kept; 0 or less becomes 365
release_format:
type: string
enum:
- raw
- attachment
default: raw
description: Deliver released messages as they are or as an attachment of a new message
exclude_domains:
type: array
items:
type: string
description: Domains and alias domains whose mail is not quarantined
sender:
type: string
description: Sender of the notifications (invalid address = empty)
subject:
type: string
description: Subject of the notifications
bcc:
type: string
description: Address that gets a copy of every notification (invalid address = empty)
redirect:
type: string
description: Address that gets all notifications instead of the mailboxes (invalid address = empty)
html_tmpl:
type: string
description: HTML template of the notifications (empty = the default template)
required:
- action
required:
- attr
example:
items:
- self
attr:
action: settings
retention_size: "20"
max_size: "15"
max_score: ""
max_age: "365"
release_format: raw
exclude_domains:
- example.com
sender: quarantine@example.org
subject: Spam Quarantine Notification
bcc: ""
redirect: ""
html_tmpl: ""
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/recipient_map/{id}:
get:
tags:
- Address Rewriting
summary: Get recipient maps
operationId: getRecipientMaps
description: >-
`all` lists the recipient maps, an ID returns one map with an extra
member `"0": null`. `{}` if there is none or the caller is no
administrator.
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a recipient map"
schema:
type: string
example: all
responses:
"200":
description: The list of recipient maps (`all`) or one recipient map
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/RecipientMap"
- $ref: "#/components/schemas/RecipientMap"
examples:
all:
summary: get/recipient_map/all
value:
- id: 1
recipient_map_old: jane.doe@example.org
recipient_map_new: jane.smith@example.org
active: 1
created: "2026-11-04 08:30:00"
modified: null
- id: 2
recipient_map_old: "@example.net"
recipient_map_new: "@example.org"
active: 0
created: "2026-11-04 08:31:12"
modified: "2026-11-05 17:02:45"
one:
summary: get/recipient_map/1
value:
id: 1
recipient_map_old: jane.doe@example.org
recipient_map_new: jane.smith@example.org
active: 1
created: "2026-11-04 08:30:00"
modified: null
"0": null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/bcc:
post:
tags:
- Address Rewriting
summary: Update BCC maps
operationId: editBccMap
description: >-
Changes the BCC maps in `items`; fields not sent keep their value,
`local_dest` cannot be changed. Same callers as add/bcc. `type` is not
validated: send only `sender` or `rcpt`.
Messages: `bcc_edited`; errors `bcc_must_be_email`, `bcc_exists`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs of the BCC maps, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
bcc_dest:
type: string
description: E-mail address that gets the copies
type:
type: string
enum:
- sender
- rcpt
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
required:
- items
- attr
example:
items:
- 3
attr:
bcc_dest: journal@example.com
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/recipient_map:
post:
tags:
- Address Rewriting
summary: Update recipient maps
operationId: editRecipientMap
description: >-
Changes the recipient maps in `items`; fields not sent keep their
value. `recipient_map_entry_exists` stops the call.
Messages: `recipient_map_entry_saved`; errors
`invalid_recipient_map_old`, `invalid_recipient_map_new`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs of the recipient maps, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
recipient_map_old:
type: string
description: Original recipient, an e-mail address or a domain
recipient_map_new:
type: string
description: New recipient, an e-mail address or a domain
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
required:
- items
- attr
example:
items:
- 1
attr:
recipient_map_new: jane.smith@example.org
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/relayhost/{id}:
get:
tags:
- Routing
summary: Get sender-dependent transports
operationId: getRelayhosts
description: >-
`all` lists the sender-dependent transports, an ID returns one; the
password is in clear text. `{}` if there is none or the caller is no
administrator.
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a sender-dependent transport"
schema:
type: string
example: all
responses:
"200":
description: The list of sender-dependent transports (`all`) or one entry
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/Relayhost"
- $ref: "#/components/schemas/Relayhost"
examples:
all:
summary: get/relayhost/all
value:
- id: 1
hostname: "[smtp.example.com]:587"
username: relay-user@example.com
password: Secret-Passphrase-42
active: 1
password_short: Sec...
used_by_domains: example.org, example.net
used_by_mailboxes: anna@example.com
one:
summary: get/relayhost/1
value:
id: 1
hostname: "[smtp.example.com]:587"
username: relay-user@example.com
password: Secret-Passphrase-42
active: 1
password_short: Sec...
used_by_domains: example.org, example.net
used_by_mailboxes: anna@example.com
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/resource/all:
get:
tags:
- Resources
summary: Get all resources
operationId: getResources
description: >-
All resources of the domains the caller manages, `{}` if none.
responses:
"200":
description: List of resources
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Resource"
example:
- name: MeetingRoom1@example.org
kind: location
multiple_bookings: 0
description: Meeting Room 1
active: 1
active_int: 1
domain: example.org
local_part: MeetingRoom1
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/resource/{id}:
get:
tags:
- Resources
summary: Get a resource
operationId: getResource
description: >-
One resource by address, `{}` if not found or no access.
parameters:
- name: id
in: path
required: true
description: Address of the resource
schema:
type: string
example: MeetingRoom1@example.org
responses:
"200":
description: The resource
content:
application/json:
schema:
$ref: "#/components/schemas/Resource"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/resource:
post:
tags:
- Resources
summary: Update resources
operationId: editResource
description: >-
Changes resources, also for domain admins; fields not sent keep their
value. The address does not change with the description.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Resource address or list of addresses
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
description:
type: string
description: Name shown in SOGo
kind:
type: string
enum:
- location
- group
- thing
multiple_bookings:
type: [integer, string]
description: 0 always free, -1 unlimited but busy when booked, n ≥ 1 at most n overlapping bookings
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
example:
items:
- MeetingRoom1@example.org
attr:
description: Meeting Room 1 (2nd floor)
multiple_bookings: -1
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/rl-mbox/{mailbox}:
get:
tags:
- Ratelimits
summary: Get the rate limit of a mailbox
operationId: getMailboxRatelimit
description: >-
The rate limit set on the mailbox; `{}` if it has none (the domain
limit applies) or no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: The rate limit
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxRatelimit"
example:
value: "100"
frame: h
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/rl-domain/{domain}:
get:
summary: Get rate limits of domains
description: >-
Rate limit (outgoing messages per time frame) of a domain or alias
domain; `all` lists all that have one.
operationId: getDomainRatelimits
tags:
- Ratelimits
parameters:
- name: domain
in: path
required: true
description: "`all` or a domain or alias domain name"
schema:
type: string
example: example.org
responses:
"200":
description: The rate limit, or the list of rate limits (`all`)
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/DomainRatelimit"
- type: array
items:
allOf:
- $ref: "#/components/schemas/DomainRatelimit"
- type: object
properties:
domain:
type: string
description: Domain or alias domain
example:
value: "100"
frame: h
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/rl-domain:
post:
summary: Set rate limits of domains
description: >-
Sets the rate limit of domains or alias domains. Needs the ACL
`ratelimit`. `rl_frame` is required also when removing the limit.
Messages: `rl_saved`; error `rl_timeframe`.
operationId: editDomainRatelimits
tags:
- Ratelimits
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Domain or alias domain name, or a list of them
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
required:
- rl_frame
properties:
rl_value:
type: [integer, string]
description: Messages per `rl_frame`; empty or 0 removes the limit
rl_frame:
type: string
enum: [s, m, h, d]
description: Time frame (second, minute, hour, day)
example:
items:
- example.org
attr:
rl_value: 100
rl_frame: h
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/rl-mbox/all:
get:
tags:
- Ratelimits
summary: Get the rate limits of all mailboxes
operationId: getMailboxRatelimits
description: >-
The rate limits set on single mailboxes the caller manages (no domain
limits). `{}` if none.
responses:
"200":
description: List of rate limits
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: "#/components/schemas/MailboxRatelimit"
- type: object
properties:
mailbox:
type: string
example:
- value: "100"
frame: h
mailbox: john.doe@example.org
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/rl-mbox:
post:
tags:
- Ratelimits
summary: Set the rate limit of mailboxes
operationId: editMailboxRatelimit
description: >-
Sets the rate limit of mailboxes: `rl_value` messages per `rl_frame`. 0
or empty removes it, but `rl_frame` must still be valid. Domain admins
need the ACL `ratelimit`. Answers `rl_saved` or `rl_timeframe`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
required:
- rl_frame
properties:
rl_value:
type: [integer, string]
description: Number of messages, 0 or empty removes the limit
rl_frame:
type: string
enum:
- s
- m
- h
- d
description: Per second, minute, hour or day
example:
items:
- john.doe@example.org
attr:
rl_value: 100
rl_frame: h
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/rlhash:
post:
tags:
- Ratelimits
summary: Reset a rate limit counter
operationId: deleteRatelimitHash
description: >-
Resets the counter of a rate-limited sender (`rl_hash` from
`get/logs/ratelimited`) so it can send again. Send one hash. Answers
`1` (not JSON) when deleted, else an empty body.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: The hash
items:
type: string
pattern: "^RL[0-9A-Za-z=]+$"
example:
- RLkfx5cv4sq1i3ehpkz5bgdhcq9u9gkzj
responses:
"200":
description: "`1` if deleted, else an empty body"
content:
application/json:
schema:
type: integer
const: 1
example: 1
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/status/containers:
get:
summary: Get container status
description: State, start time and image of all mailcow containers (also stopped ones).
operationId: getContainerStatus
tags:
- Status
responses:
"200":
description: The containers, `null` if dockerapi cannot be reached
content:
application/json:
schema:
type: object
additionalProperties:
$ref: "#/components/schemas/ContainerStatus"
example:
dovecot-mailcow:
type: info
container: dovecot-mailcow
state: running
started_at: "2026-11-10T11:00:51.541059812Z"
image: ghcr.io/mailcow/dovecot:2.3.21.1-4
postfix-mailcow:
type: info
container: postfix-mailcow
state: running
started_at: "2026-11-10T11:00:51.292779901Z"
image: ghcr.io/mailcow/postfix:1.80
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/status/vmail:
get:
summary: Get mail storage status
description: Disk usage of the file system that holds the mail storage.
operationId: getVmailStatus
tags:
- Status
responses:
"200":
description: The disk usage (`df -H` values)
content:
application/json:
schema:
type: object
properties:
type:
type: string
const: info
disk:
type: string
description: Device
used:
type: string
description: Used space
total:
type: string
description: Size of the file system
used_percent:
type: string
description: Used space in percent
example:
type: info
disk: /dev/sda1
used: 65G
total: 105G
used_percent: 66%
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/status/version:
get:
summary: Get mailcow version
description: The installed mailcow version, the release tag on master, else the short commit ID.
operationId: getVersion
tags:
- Status
responses:
"200":
description: The version
content:
application/json:
schema:
type: object
properties:
version:
type: [string, "null"]
description: Release tag or commit ID
example:
version: "2026-11"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/status/container/{id}:
get:
summary: Get container statistics
description: >-
Up to three Docker stats snapshots of one container, about five
seconds apart. Needs the full container ID, which the API does not
list; an unknown ID answers after 60 seconds with an error string.
operationId: getContainerStats
tags:
- Status
parameters:
- name: id
in: path
required: true
description: Full Docker container ID
schema:
type: string
example: 5d0f3cbb2a6e4f6c8e0e1c3b9a7d2f41b6c5e8a9d0f1e2c3b4a5968778695a4b
responses:
"200":
description: >-
Docker stats objects (see the Docker Engine API, `ContainerStats`),
oldest first; `false` without ID
content:
application/json:
schema:
type: array
items:
type: object
description: One Docker stats snapshot
properties:
read:
type: string
description: Time of the snapshot
name:
type: string
id:
type: string
cpu_stats:
type: object
precpu_stats:
type: object
memory_stats:
type: object
blkio_stats:
type: object
networks:
type: object
pids_stats:
type: object
additionalProperties: true
example:
- read: "2026-11-10T19:20:01.123456789Z"
name: /mailcowdockerized-dovecot-mailcow-1
id: 5d0f3cbb2a6e4f6c8e0e1c3b9a7d2f41b6c5e8a9d0f1e2c3b4a5968778695a4b
pids_stats:
current: 38
memory_stats:
usage: 104857600
limit: 12541669376
blkio_stats:
io_service_bytes_recursive:
- major: 8
minor: 0
op: read
value: 1052672
- major: 8
minor: 0
op: write
value: 40960
networks:
eth0:
rx_bytes: 2621440
tx_bytes: 1048576
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/status/host:
get:
summary: Get host statistics
description: CPU, memory, uptime and architecture of the Docker host.
operationId: getHostStatus
tags:
- Status
responses:
"200":
description: The host statistics
content:
application/json:
schema:
$ref: "#/components/schemas/HostStats"
example:
cpu:
cores: 4
usage: 6
memory:
total: 12541669376
usage: 62.5
swap:
- 1022357504
- 512716800
- 509640704
- 50.2
- 1392812032
- 3864260608
uptime: 703800.5492310524
system_time: "10.11.2026 19:13:07"
architecture: x86_64
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/status/host/ip:
get:
summary: Get public IP addresses
description: >-
The public IPv4 and IPv6 address of the server. Asks
ipv4.mailcow.email and ipv6.mailcow.email on every call, even with the
IP check off.
operationId: getHostIps
tags:
- Status
responses:
"200":
description: The addresses, `false` for an address that could not be determined
content:
application/json:
schema:
type: object
properties:
ipv4:
type: [string, boolean]
description: Public IPv4 address
ipv6:
type: [string, boolean]
description: Public IPv6 address
example:
ipv4: 198.51.100.25
ipv6: 2001:db8::25
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjobs/all/no_log:
get:
summary: Get all sync jobs without logs
description: >-
Like `GET /api/v1/get/syncjobs/all`, with an empty `log`.
operationId: getSyncJobsWithoutLog
tags:
- Sync jobs
responses:
"200":
description: The sync jobs
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyncJob"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjob_source/{id}:
get:
summary: Get sync source
description: >-
One sync source by id, visible as in `GET /api/v1/get/syncjob_source/all`.
operationId: getSyncJobSource
tags:
- Sync jobs
parameters:
- name: id
in: path
required: true
description: Source id
schema:
type: integer
example: 4
responses:
"200":
description: The sync source
content:
application/json:
schema:
$ref: "#/components/schemas/SyncJobSource"
example:
id: 4
name: Google Workspace
description: ""
created_by: admin
scope: all
host1: imap.gmail.com
port1: 993
enc1: SSL
verify_cert: 1
auth_type: XOAUTH2
oauth_flow: authorization_code
oauth_token_endpoint: https://oauth2.googleapis.com/token
oauth_authorize_endpoint: https://accounts.google.com/o/oauth2/v2/auth
oauth_userinfo_endpoint: null
oauth_client_id: 1234567890-example.apps.googleusercontent.com
oauth_scope: https://mail.google.com/ openid email
oauth_extra_params: '{"access_type":"offline","prompt":"consent"}'
oauth_token_expires: null
oauth_last_refresh_error: null
oauth_last_refresh_attempt: null
created: "2026-11-01 10:00:00"
modified: null
active: 1
domains: []
users: []
can_edit: true
host: imap.gmail.com
port: 993
enc: SSL
has_client_secret: true
has_access_token: false
oauth_redirect_uri: https://mail.example.org/syncjob-oauth
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjob_options:
get:
summary: Get allowed custom imapsync options
description: >-
The imapsync options allowed in `custom_params`, with their rule: `true`
needs a value, `false` takes none, a string is a regular expression the
whole value must match. Options that run code, use local files or print
secrets are never allowed. Every logged-in user may read it.
operationId: getSyncJobOptions
tags:
- Sync jobs
responses:
"200":
description: Option name => rule
content:
application/json:
schema:
type: object
additionalProperties:
type:
- boolean
- string
example:
authmd51: false
debugssl: true
folder: true
maxsize: true
syncinternaldates: false
sslargs1: "^SSL_verify_mode=[01]$"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/imapsync_settings:
get:
summary: Get global sync job settings
description: >-
Settings of the sync job runner.
operationId: getSyncJobSettings
tags:
- Sync jobs
responses:
"200":
description: The settings
content:
application/json:
schema:
$ref: "#/components/schemas/SyncJobSettings"
example:
max_parallel: 3
max_bytes_per_second: 2048000
max_kb_per_second: 2000
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjobs/all:
get:
summary: Get all sync jobs
description: >-
All sync jobs with their logs, in queue order. Admins also get jobs of
deleted mailboxes, domain admins the jobs of their mailboxes; users get
none, see `GET /api/v1/get/syncjobs/{mailbox}`.
operationId: getSyncJobs
tags:
- Sync jobs
responses:
"200":
description: The sync jobs
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyncJob"
example:
- id: 12
user2: alice@example.org
regextrans2: ""
authmd51: 0
domain2: ""
subfolder2: Imported
user1: alice@old-provider.example.com
exclude: "(?i)spam|(?i)junk"
maxage: 0
mins_interval: 20
maxbytespersecond: "0"
delete2duplicates: 1
delete1: 0
delete2: 0
automap: 1
skipcrossduplicates: 0
custom_params: '[{"o":"folder","v":"INBOX"}]'
timeout1: 600
timeout2: 600
subscribeall: 1
dry: 0
is_running: 0
last_run: "2026-11-09 08:20:01"
success: 1
exit_status: EX_OK
created: "2026-11-03 09:40:09"
modified: "2026-11-03 09:42:21"
active: 1
source_id: 3
custom_params_legacy: null
prio: 0
source_name: Old provider
source_description: Migration from the old provider
source_host: imap.example.com
source_port: 993
source_enc: SSL
source_auth_type: PLAIN
source_created_by: API
source_scope: domain
source_oauth_flow: client_credentials
source_active: 1
source_oauth_token_expires: null
source_oauth_last_refresh_error: null
user_token_expires: null
user_token_error: null
user_token_exists: 0
log: "Transfer started at Mon Nov 9 08:20:02 2026\n..."
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjobs/{mailbox}:
get:
summary: Get sync jobs of a mailbox
description: >-
The sync jobs of a local mailbox with their logs, in queue order.
Domain admins may read their mailboxes, users their own. A value that is
no email address returns the caller's own jobs.
operationId: getMailboxSyncJobs
tags:
- Sync jobs
parameters:
- name: mailbox
in: path
required: true
description: Local mailbox (`user2` of the jobs)
schema:
type: string
example: alice@example.org
responses:
"200":
description: The sync jobs of the mailbox
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyncJob"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjobs/{mailbox}/no_log:
get:
summary: Get sync jobs of a mailbox without logs
description: >-
Like `GET /api/v1/get/syncjobs/{mailbox}`, with an empty `log`.
operationId: getMailboxSyncJobsWithoutLog
tags:
- Sync jobs
parameters:
- name: mailbox
in: path
required: true
description: Local mailbox (`user2` of the jobs)
schema:
type: string
example: alice@example.org
responses:
"200":
description: The sync jobs of the mailbox
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyncJob"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/syncjob_source/all:
get:
summary: Get sync sources
description: >-
The sync sources the caller may see, ordered by name. Domain admins see
their own, `all` sources and those for their domains or mailboxes or
created by their mailboxes; users their own, `all` sources and those
for them or their domain.
operationId: getSyncJobSources
tags:
- Sync jobs
responses:
"200":
description: The sync sources
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SyncJobSource"
example:
- id: 3
name: Old provider
description: Migration from the old provider
created_by: API
scope: domain
host1: imap.example.com
port1: 993
enc1: SSL
verify_cert: 1
auth_type: PLAIN
oauth_flow: client_credentials
oauth_token_endpoint: null
oauth_authorize_endpoint: null
oauth_userinfo_endpoint: null
oauth_client_id: null
oauth_scope: null
oauth_extra_params: null
oauth_token_expires: null
oauth_last_refresh_error: null
oauth_last_refresh_attempt: null
created: "2026-11-03 09:42:21"
modified: null
active: 1
domains:
- example.org
users: []
can_edit: true
host: imap.example.com
port: 993
enc: SSL
has_client_secret: false
has_access_token: false
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/tls-policy-map/{id}:
get:
tags:
- Outgoing TLS Policy Map Overrides
summary: Get TLS policy maps
operationId: getTlsPolicyMaps
description: >-
`all` lists the TLS policy maps, an ID returns one map with an extra
member `"0": null`. `{}` if there is none or the caller is no
administrator.
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a TLS policy map"
schema:
type: string
example: all
responses:
"200":
description: The list of TLS policy maps (`all`) or one TLS policy map
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/TlsPolicyMap"
- $ref: "#/components/schemas/TlsPolicyMap"
examples:
all:
summary: get/tls-policy-map/all
value:
- id: 2
dest: example.com
policy: encrypt
parameters: protocols=>=TLSv1.2
active: 1
created: "2026-11-06 12:00:31"
modified: null
one:
summary: get/tls-policy-map/2
value:
id: 2
dest: example.com
policy: encrypt
parameters: protocols=>=TLSv1.2
active: 1
created: "2026-11-06 12:00:31"
modified: null
"0": null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/tls-policy-map:
post:
tags:
- Outgoing TLS Policy Map Overrides
summary: Update TLS policy maps
operationId: editTlsPolicyMap
description: >-
Changes the TLS policy maps in `items`; fields not sent keep their
value. An error stops the call; an existing destination answers
`recipient_map_entry_exists`.
Messages: `tls_policy_map_entry_saved`; errors
`tls_policy_map_dest_invalid`, `tls_policy_map_parameter_invalid`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs of the TLS policy maps, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
dest:
type: string
description: Destination, e.g. `example.org` or `[mail.example.org]:25`
policy:
type: string
enum:
- none
- may
- encrypt
- dane
- dane-only
- fingerprint
- verify
- secure
parameters:
type: string
description: Empty or space-separated `name=value` attributes
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
required:
- items
- attr
example:
items:
- 2
attr:
policy: dane
parameters: ""
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/transport/{id}:
get:
tags:
- Routing
summary: Get transport maps
operationId: getTransports
description: >-
`all` lists the transport maps, an ID returns one; the password is in
clear text. `{}` if there is none or the caller is no administrator.
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a transport map"
schema:
type: string
example: all
responses:
"200":
description: The list of transport maps (`all`) or one entry
content:
application/json:
schema:
anyOf:
- type: array
items:
$ref: "#/components/schemas/Transport"
- $ref: "#/components/schemas/Transport"
examples:
all:
summary: get/transport/all
value:
- id: 4
is_mx_based: 0
destination: example.com
nexthop: "[mx.example.com]:25"
username: ""
password: ""
active: 1
password_short: "..."
- id: 5
is_mx_based: 1
destination: .*\.google\.com
nexthop: "[smtp.example.net]:587"
username: relay-user@example.net
password: Secret-Passphrase-42
active: 1
password_short: Sec...
one:
summary: get/transport/4
value:
id: 4
is_mx_based: 0
destination: example.com
nexthop: "[mx.example.com]:25"
username: ""
password: ""
active: 1
password_short: "..."
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/relayhost:
post:
tags:
- Routing
summary: Update sender-dependent transports
operationId: editRelayhost
description: >-
Changes the sender-dependent transports in `items`; fields not sent
and an empty `hostname` keep their value.
Messages: `object_modified`; errors `relayhost_invalid`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs of the sender-dependent transports, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
hostname:
type: string
description: Next hop, e.g. `[smtp.example.com]:587`
username:
type: string
description: SMTP user name, empty for no authentication
password:
type: string
description: SMTP password
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
required:
- items
- attr
example:
items:
- 1
attr:
password: New-Secret-Passphrase-43
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/transport:
post:
tags:
- Routing
summary: Update transport maps
operationId: editTransport
description: >-
Changes the transport maps in `items`; fields not sent keep their
value. An empty `username` also clears the password; credentials apply
to all entries of the next hop. Destination and next-hop errors stop
the call.
Messages: `object_modified`; errors `relayhost_invalid`,
`transport_dest_exists`, `invalid_destination`, `next_hop_interferes`.
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: IDs of the transport maps, a single value or a list
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
destination:
type: string
description: One destination (see add/transport)
nexthop:
type: string
description: Next hop, e.g. `[mx.example.com]:25`
username:
type: string
description: SMTP user name; empty removes the credentials
password:
type: string
description: SMTP password
is_mx_based:
type: [boolean, integer, string]
description: 1 = `destination` is a regular expression for MX names
active:
type: [boolean, integer, string]
description: 1 = active, 0 = inactive
required:
- items
- attr
example:
items:
- 4
attr:
nexthop: "[mx2.example.com]:25"
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/cors:
post:
summary: Edit CORS settings
description: >-
Sets the origins and methods allowed to call the API from a browser. A
missing value is reset to its default.
Messages: `cors_headers_edited`; errors `cors_invalid_origin`,
`cors_invalid_method`.
operationId: editCors
tags:
- Cross-Origin Resource Sharing (CORS)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
allowed_origins:
description: >-
`scheme://host[:port]` (http/https, no path) or `*`; a
list or one origin per line. Default: the mailcow URL.
oneOf:
- type: array
items:
type: string
- type: string
allowed_methods:
description: >-
Uppercase; a list or a string with single separators
(`GET,POST`, not `GET, POST`). Default: all four.
oneOf:
- type: array
items:
type: string
enum:
- GET
- POST
- PUT
- DELETE
- type: string
required:
- attr
example:
attr:
allowed_origins:
- https://app.example.org
- https://admin.example.com:8443
allowed_methods:
- GET
- POST
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/spam-score/{mailbox}:
get:
tags:
- Mailbox user settings
summary: Get the spam score of a mailbox
operationId: getSpamScore
description: >-
The spam thresholds of the mailbox, its own or the server default. `{}`
without access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: Thresholds
content:
application/json:
schema:
$ref: "#/components/schemas/SpamScore"
example:
score: "6,12"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/spam-score:
post:
tags:
- Mailbox user settings
summary: Set the spam score of mailboxes
operationId: editSpamScore
description: >-
Sets the spam thresholds of the mailboxes: from the first value mail
goes to junk, from the second it is rejected. `default` removes the own
values. Needs the user ACL `spam_score`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
$ref: "#/components/schemas/MailboxItems"
attr:
type: object
required:
- spam_score
properties:
spam_score:
type: string
description: '"low,high" (numbers) or "default"'
examples:
- "6,12"
- default
example:
items:
- john.doe@example.org
attr:
spam_score: "6,12"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/mailbox/template:
post:
tags:
- Mailboxes
summary: Create a mailbox template
operationId: addMailboxTemplate
description: >-
Saves a named set of mailbox settings that `add/mailbox` uses as
defaults. Without `acl` it grants no user ACL.
Messages: `template_added`; errors `template_exists`,
`quarantine_category_invalid`.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- template
properties:
template:
type: string
description: Name of the template
- $ref: "#/components/schemas/MailboxTemplateInput"
example:
template: Sales
quota: 2048
tags:
- sales
quarantine_notification: daily
quarantine_category: reject
rl_value: 100
rl_frame: h
active: 1
protocol_access:
- imap
- smtp
- sieve
acl:
- spam_alias
- spam_score
- app_passwds
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/mailbox/all:
get:
tags:
- Mailboxes
summary: Get all mailboxes
operationId: getMailboxes
description: >-
All mailboxes of the domains the caller manages, without resources.
`{}` if none.
parameters:
- $ref: "#/components/parameters/MailboxTagsQuery"
responses:
"200":
description: List of mailboxes
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Mailbox"
examples:
mailboxes:
$ref: "#/components/examples/MailboxList"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/all/{domains}:
get:
tags:
- Mailboxes
summary: Get the mailboxes of domains
operationId: getMailboxesOfDomains
description: >-
Like `get/mailbox/all` for the given domains. Caution: an unknown or
foreign domain adds all mailboxes the caller manages.
parameters:
- name: domains
in: path
required: true
description: Domain name or comma-separated list of domain names
schema:
type: string
example: example.org
- $ref: "#/components/parameters/MailboxTagsQuery"
responses:
"200":
description: List of mailboxes
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Mailbox"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/reduced:
get:
tags:
- Mailboxes
summary: Get all mailboxes (reduced details)
operationId: getMailboxesReduced
description: >-
Like `get/mailbox/all` without the costly fields named in `Mailbox`;
faster on large installations.
parameters:
- $ref: "#/components/parameters/MailboxTagsQuery"
responses:
"200":
description: List of mailboxes
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Mailbox"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/reduced/{domains}:
get:
tags:
- Mailboxes
summary: Get the mailboxes of domains (reduced details)
operationId: getMailboxesReducedOfDomains
description: >-
Like `get/mailbox/reduced` for the given domains; an unknown domain
adds all mailboxes the caller manages.
parameters:
- name: domains
in: path
required: true
description: Domain name or comma-separated list of domain names
schema:
type: string
example: example.org,example.com
- $ref: "#/components/parameters/MailboxTagsQuery"
responses:
"200":
description: List of mailboxes
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Mailbox"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/template/all:
get:
tags:
- Mailboxes
summary: Get all mailbox templates
operationId: getMailboxTemplates
description: >-
All mailbox templates, also for domain admins. `{}` if none.
responses:
"200":
description: List of templates
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/MailboxTemplate"
example:
- id: 2
template: Default
type: mailbox
attributes:
tags: []
quota: 0
quarantine_notification: hourly
quarantine_category: reject
rl_frame: s
rl_value: ""
force_pw_update: 0
force_tfa: 0
sogo_access: 1
active: 1
tls_enforce_in: 0
tls_enforce_out: 0
imap_access: 1
pop3_access: 1
smtp_access: 1
sieve_access: 1
eas_access: 1
dav_access: 1
acl_spam_alias: 1
acl_tls_policy: 1
acl_spam_score: 1
acl_spam_policy: 1
acl_delimiter_action: 1
acl_syncjobs: 0
acl_eas_reset: 1
acl_sogo_profile_reset: 0
acl_pushover: 1
acl_quarantine: 1
acl_quarantine_attachments: 1
acl_quarantine_notification: 1
acl_quarantine_category: 1
acl_app_passwds: 1
created: "2026-09-21 10:23:08"
modified: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/mailbox/template/{id}:
get:
tags:
- Mailboxes
summary: Get a mailbox template
operationId: getMailboxTemplate
description: >-
One mailbox template by ID, also for domain admins. `{}` if not found.
parameters:
- name: id
in: path
required: true
description: Template ID
schema:
type: integer
example: 2
responses:
"200":
description: The template
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxTemplate"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/mailbox/template:
post:
tags:
- Mailboxes
summary: Update mailbox templates
operationId: editMailboxTemplate
description: >-
Changes mailbox templates and passes the change on to mailboxes that
use them as group template. `Default` keeps its name. Send the complete
template: fields not sent are reset (`quota` to 0, protocol and ACL
settings lost), and `quarantine_category` is required.
Messages: `template_modified`; errors `template_id_invalid`,
`quarantine_category_invalid`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Template ID or list of template IDs
oneOf:
- type: integer
- type: array
items:
type: integer
attr:
allOf:
- type: object
properties:
template:
type: string
description: New name of the template (not for "Default")
- $ref: "#/components/schemas/MailboxTemplateInput"
example:
items:
- 3
attr:
template: Sales
quota: 4096
tags:
- sales
tagged_mail_handler: subfolder
quarantine_notification: daily
quarantine_category: reject
rl_value: 100
rl_frame: h
force_pw_update: 0
force_tfa: 0
sogo_access: 1
active: 1
tls_enforce_in: 0
tls_enforce_out: 1
protocol_access:
- imap
- smtp
- sieve
- dav
acl:
- spam_alias
- spam_score
- delimiter_action
- app_passwds
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/rename-mbox:
post:
tags:
- Mailboxes
summary: Rename a mailbox
operationId: renameMailbox
description: >-
Renames `old_local_part@domain` to `new_local_part@domain`, including
maildir, aliases and SOGo account. The mailbox is named in `attr`, not
`items`, and must be active (1 or 2). Also for domain admins. Answers
`mailbox_renamed`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- attr
properties:
items:
description: Not used
attr:
type: object
required:
- domain
- old_local_part
- new_local_part
properties:
domain:
type: string
description: Domain of the mailbox
old_local_part:
type: string
description: Current local part
new_local_part:
type: string
description: New local part
create_alias:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
description: 1 creates an alias from the old to the new address
example:
items: []
attr:
domain: example.org
old_local_part: john.doe
new_local_part: john
create_alias: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/mailbox/template:
post:
tags:
- Mailboxes
summary: Delete mailbox templates
operationId: deleteMailboxTemplate
description: >-
Deletes mailbox templates by ID; `Default` is kept silently. Answers
`template_removed`.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Template IDs
items:
type: integer
example:
- 3
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/last-login/{mailbox}:
get:
tags:
- Mailboxes
summary: Get the last logins of a mailbox
operationId: getLastLogin
description: >-
Logins of the mailbox in the last 7 days (`sasl`, the latest per
address, service and app password) and its previous UI login (`ui`,
only for admins and the mailbox user itself).
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: Logins
content:
application/json:
schema:
$ref: "#/components/schemas/LastLogin"
example:
ui:
remote: 198.51.100.23
time: 1793011200
sasl:
- real_rip: 198.51.100.23
datetime: "2026-11-09 08:12:44"
service: imap
app_password: 23
app_password_name: Thunderbird
location: DE
- real_rip: Web/EAS/Internal (172.22.1.248)
datetime: "2026-11-08 17:03:10"
service: SOGO
app_password: 0
app_password_name: null
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/last-login/{mailbox}/{days}:
get:
tags:
- Mailboxes
summary: Get the last logins of a mailbox for a period
operationId: getLastLoginDays
description: >-
Like `get/last-login/{mailbox}` for the last `{days}` days; values
below 1 mean 7.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
- name: days
in: path
required: true
description: Number of days
schema:
type: integer
minimum: 1
example: 30
responses:
"200":
description: Logins
content:
application/json:
schema:
$ref: "#/components/schemas/LastLogin"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/reset-last-login/{mailbox}:
get:
tags:
- Mailboxes
summary: Clear the login history of a mailbox
operationId: resetLastLogin
description: >-
Deletes the login history of the mailbox. A `get` route that changes
data: read-only API keys can call it. Always answers `true`.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: Done
content:
application/json:
schema:
type: boolean
example: true
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/delete/eas_cache:
post:
tags:
- Mailboxes
summary: Reset the ActiveSync devices of mailboxes
operationId: deleteEasCache
description: >-
Deletes the ActiveSync device cache of the mailboxes, so devices sync
from scratch. Needs the user ACL `eas_reset`; a mailbox user may reset
only its own.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxItems"
example:
- john.doe@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/sogo_profile:
post:
tags:
- Mailboxes
summary: Reset the SOGo profile of mailboxes
operationId: deleteSogoProfile
description: >-
Deletes the SOGo data of the mailboxes: profile, settings, calendars
and address books. Needs the user ACL `sogo_profile_reset`; a mailbox
user may reset only its own.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxItems"
example:
- john.doe@example.org
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/bcc-destination-options:
get:
tags:
- Mailboxes
summary: Get the possible BCC map destinations
operationId: getBccDestinationOptions
description: >-
What a BCC map can be bound to: the caller's domains, their mailboxes
with their aliases, and alias domains. Empty keys are left out.
responses:
"200":
description: Domains, mailboxes with their addresses, alias domains
content:
application/json:
schema:
type: object
properties:
domains:
type: array
items:
type: string
mailboxes:
type: object
description: Mailbox address → the mailbox and its aliases
additionalProperties:
type: array
items:
type: string
alias_domains:
type: array
items:
type: string
example:
domains:
- example.org
mailboxes:
john.doe@example.org:
- john.doe@example.org
- sales@example.org
jane.roe@example.org:
- jane.roe@example.org
alias_domains:
- example.net
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/search/mailbox:
post:
tags:
- Mailboxes
summary: Search mailboxes page by page
operationId: searchMailboxes
description: >-
Server-side search behind the UI mailbox table (DataTables format) over
the mailboxes the caller manages. Read-only API keys may use it;
mailbox users get `403`.
Columns: 2 address, 3 quota, 4 last mail login, 5 last password change,
6 quota in use, 7 name, 20 messages, 23 tags, 24 active. Send 4, 5, 6
and 20 as not searchable and 23 as not orderable, else the query fails.
`recordsTotal` equals `recordsFiltered`.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MailboxSearchRequest"
example:
draw: 1
start: 0
length: 25
search:
value: john
order:
- column: 2
dir: asc
columns:
- searchable: false
orderable: false
- searchable: false
orderable: false
- data: username
searchable: true
orderable: true
- searchable: false
orderable: true
- searchable: false
orderable: true
- searchable: false
orderable: true
- searchable: false
orderable: true
- data: name
searchable: true
orderable: true
responses:
"200":
description: >-
One page of mailboxes. A failing database query answers
`{"error": "An SQL error occurred: ..."}` instead.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/MailboxSearchResult"
- type: object
properties:
error:
type: string
examples:
page:
$ref: "#/components/examples/MailboxSearchPage"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
description: The caller is a mailbox user or not logged in
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
type: error
msg: Insufficient permissions
/api/v1/edit/identity-provider:
post:
summary: Configure the Identity Provider
description: >-
Saves the Identity Provider configuration (Keycloak, generic OpenID
Connect or LDAP). Send the complete configuration including the secrets:
settings not sent are reset to their defaults. Changing the LDAP
`id_attribute` drops the stored links; mailboxes are matched by email
again.
Messages: `object_modified`; errors `required_data_missing`,
`invalid_authsource`, `authsource_in_use`.
operationId: editIdentityProvider
tags:
- Identity Provider
requestBody:
content:
application/json:
schema:
type: object
required:
- attr
properties:
items:
description: Not used
attr:
$ref: "#/components/schemas/IdentityProviderAttributes"
examples:
keycloak:
value:
attr:
authsource: keycloak
server_url: https://auth.example.org
realm: mailcow
client_id: mailcow
client_secret: client-secret-value
redirect_url: https://mail.example.org
redirect_url_extra:
- https://webmail.example.org
version: 26.1.3
login_provisioning: 1
mailpassword_flow: 0
periodic_sync: 1
import_users: 1
sync_interval: 15
offboarding: 1
offboarding_limit: 10
group_sync: 1
group_autocreate: 1
group_paths: /mailcow/*
group_default_domain: example.org
default_template: Default
mappers:
- staff
templates:
- Staff
ldap:
value:
attr:
authsource: ldap
host: ldap1.example.org,ldap2.example.org
port: 636
use_ssl: 1
use_tls: 0
ignore_ssl_error: 0
basedn: dc=example,dc=org
binddn: cn=mailcow,ou=services,dc=example,dc=org
bindpass: bind-password
username_field: mail
filter: (objectClass=inetOrgPerson)
attribute_field: departmentNumber
login_provisioning: 1
periodic_sync: 1
import_users: 1
sync_interval: 30
group_sync: 1
group_filter: (objectClass=groupOfNames)
group_member_mode: member
group_member_attribute: member
default_template: Default
generic-oidc:
value:
attr:
authsource: generic-oidc
authorize_url: https://sso.example.org/application/o/authorize/
token_url: https://sso.example.org/application/o/token/
userinfo_url: https://sso.example.org/application/o/userinfo/
client_id: mailcow
client_secret: client-secret-value
redirect_url: https://mail.example.org
client_scopes: openid profile email mailcow_template
login_provisioning: 1
default_template: Default
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/identity-provider:
get:
summary: Get Identity Provider settings
description: >-
The stored Identity Provider settings, also those of providers
configured before. Read/write API keys get the secrets in plain text,
read-only keys `*`. Without a configuration it answers
`{"login_provisioning": 1}`.
operationId: getIdentityProvider
tags:
- Identity Provider
responses:
"200":
description: The settings
content:
application/json:
schema:
$ref: "#/components/schemas/IdentityProviderSettings"
example:
authsource: keycloak
server_url: https://auth.example.org
realm: mailcow
client_id: mailcow
client_secret: "*"
redirect_url: https://mail.example.org
redirect_url_extra:
- https://webmail.example.org
version: 26.1.3
mailpassword_flow: "0"
periodic_sync: "1"
import_users: "1"
sync_interval: "15"
ignore_ssl_error: false
login_provisioning: true
group_paths: /mailcow/*
offboarding: "1"
offboarding_limit: "10"
group_sync: "1"
group_autocreate: "1"
group_default_domain: example.org
default_template: Default
mappers:
- staff
templates:
- Staff
access_token: "*"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/identity-provider-test:
post:
summary: Test an Identity Provider connection
description: >-
Tests the connection data in `attr` without storing it; stored settings
are not used, so send the secrets too. Keycloak must issue a
client_credentials token and generic-oidc answer OPTIONS on `token_url`
(HTTP 200 within 7 s); LDAP must bind. The answer has no details, and a
missing or unknown `authsource` answers success without a test.
operationId: testIdentityProvider
tags:
- Identity Provider
requestBody:
content:
application/json:
schema:
type: object
required:
- attr
properties:
items:
description: Not used
attr:
type: object
required:
- authsource
properties:
authsource:
type: string
enum:
- keycloak
- generic-oidc
- ldap
server_url:
type: string
description: Keycloak base URL
realm:
type: string
description: Keycloak realm
client_id:
type: string
description: Keycloak client id
client_secret:
type: string
description: Keycloak client secret
token_url:
type: string
description: generic-oidc token endpoint
ignore_ssl_error:
type:
- boolean
- integer
- string
description: Do not verify the TLS certificate
host:
type: string
description: LDAP host, or several separated by commas
port:
type:
- integer
- string
description: LDAP port
basedn:
type: string
binddn:
type: string
bindpass:
type: string
use_ssl:
type:
- boolean
- integer
- string
description: LDAPS
use_tls:
type:
- boolean
- integer
- string
description: StartTLS, ignored with `use_ssl`
example:
attr:
authsource: keycloak
server_url: https://auth.example.org
realm: mailcow
client_id: mailcow
client_secret: client-secret-value
ignore_ssl_error: 0
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/identity-provider:
post:
summary: Delete the Identity Provider configuration
description: >-
Deletes all Identity Provider settings, mailbox links and the sync
history. Refused while any mailbox uses an external provider. The body
must be valid JSON, e.g. `[]`.
Messages: `item_deleted`; errors `authsource_in_use`.
operationId: deleteIdentityProvider
tags:
- Identity Provider
requestBody:
content:
application/json:
schema:
description: Not used, any JSON value
example: []
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/filter:
post:
tags:
- Mailbox filters
summary: Create a Sieve filter
operationId: addFilter
description: >-
Adds a Sieve script to a mailbox. Needs the ACL `filters` (admins,
domain admins). Activating a filter deactivates the other filters of
the same type and mailbox.
Messages: `mailbox_modified`; errors `sieve_error`, `no_user_defined`,
`script_empty`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
- script_data
- script_desc
- filter_type
properties:
username:
type: string
description: Mailbox of the filter
script_desc:
type: string
description: Description
script_data:
type: string
description: The Sieve script
filter_type:
type: string
enum:
- prefilter
- postfilter
description: Runs before (prefilter) or after (postfilter) the user's own filters
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
default: 0
example:
username: john.doe@example.org
script_desc: Move newsletters
script_data: |-
require "fileinto";
if header :contains "List-Id" "newsletter" {
fileinto "Newsletters";
}
filter_type: prefilter
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/filters/all:
get:
tags:
- Mailbox filters
summary: Get all Sieve filters
operationId: getFilters
description: >-
The Sieve filters of all mailboxes the caller manages, `{}` if none.
responses:
"200":
description: List of filters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SieveFilter"
example:
- active: 1
id: 7
username: john.doe@example.org
filter_type: prefilter
script_data: |-
require "fileinto";
if header :contains "List-Id" "newsletter" {
fileinto "Newsletters";
}
script_desc: Move newsletters
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/filters/{mailbox}:
get:
tags:
- Mailbox filters
summary: Get the Sieve filters of a mailbox
operationId: getMailboxFilters
description: >-
The Sieve filters of the mailbox, `{}` if none or no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: List of filters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SieveFilter"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/filter:
post:
tags:
- Mailbox filters
summary: Update Sieve filters
operationId: editFilter
description: >-
Changes filters by ID; fields not sent keep their value. Needs the ACL
`filters` (admins, domain admins). Activating a filter deactivates the
others of the same type and mailbox. An unknown ID answers
`access_denied`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
items:
description: Filter ID or list of IDs
oneOf:
- type: integer
- type: array
items:
type: integer
attr:
type: object
properties:
script_desc:
type: string
script_data:
type: string
filter_type:
type: string
enum:
- prefilter
- postfilter
active:
type: [integer, string]
enum: [0, 1, "0", "1"]
example:
items:
- 7
attr:
active: 0
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/filter:
post:
tags:
- Mailbox filters
summary: Delete Sieve filters
operationId: deleteFilter
description: >-
Deletes filters by ID; IDs that are not numeric are skipped. Needs the
ACL `filters` (admins, domain admins).
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Filter IDs
items:
type: integer
example:
- 7
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/active-user-sieve/{mailbox}:
get:
tags:
- Mailbox filters
summary: Get the active Sieve script of a mailbox
operationId: getActiveUserSieve
description: >-
The Sieve script the user activated in a mail client or SOGo, as a list
with one string. `{}` if none or no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: The script as the only element of a list
content:
application/json:
schema:
type: array
maxItems: 1
items:
type: string
example:
- |-
require ["fileinto"];
if header :contains "subject" "invoice" {
fileinto "Invoices";
}
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/mailbox-policy:
post:
tags:
- Mailbox antispam policies
summary: Add a sender to the allow or deny list of a mailbox
operationId: addMailboxPolicy
description: >-
Adds a sender to the allow list (`wl`, never spam) or deny list (`bl`,
rejected) of a mailbox. Needs the user ACL `spam_policy`.
Messages: `mailbox_modified`; errors `policy_list_from_invalid`,
`policy_list_from_exists`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
- object_list
- object_from
properties:
username:
type: string
description: Mailbox
object_list:
type: string
enum:
- wl
- bl
description: wl = allow list, bl = deny list
object_from:
type: string
description: "Sender address, domain or pattern; allowed: letters, digits, `@ _ . - *`"
example:
username: john.doe@example.org
object_list: bl
object_from: "*@spam.example.com"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/policy_wl_mailbox/{mailbox}:
get:
tags:
- Mailbox antispam policies
summary: Get the allow list of a mailbox
operationId: getMailboxPolicyAllowList
description: >-
The allow list entries of the mailbox and of its domain (see `object`).
`{}` if none or no access.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: List of entries
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SpamPolicyEntry"
example:
- object: john.doe@example.org
value: "*@partner.example.com"
prefid: 12
- object: example.org
value: newsletter@example.net
prefid: 4
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/policy_bl_mailbox/{mailbox}:
get:
tags:
- Mailbox antispam policies
summary: Get the deny list of a mailbox
operationId: getMailboxPolicyDenyList
description: >-
Like `get/policy_wl_mailbox/{mailbox}` for the deny list.
parameters:
- name: mailbox
in: path
required: true
description: Mailbox address
schema:
type: string
example: john.doe@example.org
responses:
"200":
description: List of entries
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SpamPolicyEntry"
example:
- object: john.doe@example.org
value: "*@spam.example.com"
prefid: 13
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/delete/mailbox-policy:
post:
tags:
- Mailbox antispam policies
summary: Delete allow or deny list entries of mailboxes
operationId: deleteMailboxPolicy
description: >-
Deletes allow or deny list entries of mailboxes by `prefid`. Needs the
user ACL `spam_policy`. Domain entries are refused; use
`delete/domain-policy`.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: prefid values
items:
type: integer
example:
- 13
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/rsetting:
post:
summary: Add Rspamd settings rule
description: >-
Adds a rule to the Rspamd settings map. `content` is an Rspamd settings
entry; `GET /api/v1/get/presets/rspamd` has examples. Without `desc`
nothing is saved and the answer is empty.
Messages: `settings_map_added`; errors `map_content_empty`.
operationId: addRspamdSetting
tags:
- Rspamd
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RspamdSettingAttributes"
example:
desc: Disable all but DKIM and rate limit for authenticated users
content: |-
priority = 10;
authenticated = yes;
apply "default" {
symbols_enabled = ["DKIM_SIGNED", "RATELIMITED", "RATELIMIT_UPDATE", "RATELIMIT_CHECK"];
}
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/rsetting/{id}:
get:
summary: Get Rspamd settings rules
description: >-
Returns one rule of the Rspamd settings map, or a list of all rules
with `all`.
operationId: getRspamdSettings
tags:
- Rspamd
parameters:
- name: id
in: path
required: true
description: "`all` or the ID of a rule"
schema:
type: string
example: all
responses:
"200":
description: The rule, or the list of rules for `all`
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: "#/components/schemas/RspamdSetting"
- $ref: "#/components/schemas/RspamdSetting"
example:
- id: 1
desc: Disable Rspamd for example.org
content: |-
priority = 10;
rcpt = "/.*@example\.org$/";
from = "/.*/";
apply "default" {
MAILCOW_WHITE = -9999.0;
}
symbols [
"MAILCOW_WHITE"
]
active: 1
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/rsetting:
post:
summary: Edit Rspamd settings rules
description: >-
Changes rules of the Rspamd settings map. Fields not sent, and an empty
`desc` or `content`, keep the old value.
Messages: `object_modified`; errors `settings_map_invalid`.
operationId: editRspamdSetting
tags:
- Rspamd
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: ID or list of IDs of the rules
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
attr:
type: object
properties:
desc:
type: string
description: Short description (empty = keep)
content:
type: string
description: Rule content (empty = keep)
active:
type: [boolean, integer, string]
description: 1 = the rule is handed to Rspamd, 0 = inactive (not sent = keep)
required:
- items
- attr
example:
items:
- 1
attr:
desc: Disable Rspamd for example.org
active: "0"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/rsetting:
post:
summary: Delete Rspamd settings rules
description: >-
Deletes rules of the Rspamd settings map. Answers
`settings_map_removed` for every ID, even unknown ones.
operationId: deleteRspamdSettings
tags:
- Rspamd
requestBody:
content:
application/json:
schema:
description: IDs of the rules (a single ID works too)
oneOf:
- type: array
items:
type: [integer, string]
- type: [integer, string]
example:
- 1
- 2
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/rspamd-map:
post:
summary: Edit Rspamd global regex maps
description: >-
Replaces the content of global Rspamd regex maps (Global filters in the
UI). One regular expression per line, `#` starts a comment; unlike the
UI, the API does not check the expressions. Each map takes about a
second.
Messages: `object_modified`; errors `global_map_invalid`,
`global_map_write_error`.
operationId: editRspamdMap
tags:
- Rspamd
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: File name or list of file names of the maps; all of them get the same content
oneOf:
- type: array
items:
$ref: "#/components/schemas/RspamdRegexMap"
- $ref: "#/components/schemas/RspamdRegexMap"
attr:
type: object
properties:
rspamd_map_data:
type: string
description: New content of the map (trimmed, replaces the whole file)
required:
- rspamd_map_data
required:
- items
- attr
example:
items:
- global_smtp_from_blacklist.map
attr:
rspamd_map_data: |-
# Envelope senders to reject
/^spammer@example\.com$/i
/@spam\.example\.net$/i
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/rspamd/actions:
get:
summary: Get Rspamd action statistics
description: >-
Returns how many messages Rspamd handled with each action, as
`[action, count]` pairs. Greylisted messages count as `soft reject`.
`{}` when Rspamd does not answer.
operationId: getRspamdActions
tags:
- Rspamd
responses:
"200":
description: List of `[action, count]` pairs
content:
application/json:
schema:
type: array
items:
type: array
prefixItems:
- type: string
description: Rspamd action
- type: integer
description: Number of messages
minItems: 2
maxItems: 2
example:
- - reject
- 38
- - soft reject
- 1
- - rewrite subject
- 0
- - add header
- 6
- - no action
- 255
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/presets/{kind}:
get:
summary: Get Rspamd or Sieve presets
description: >-
Returns the example presets of the UI: `rspamd` for Rspamd settings
rules, `sieve` for Sieve filters. `headline` is in the session
language. Admins and domain admins.
operationId: getPresets
tags:
- Rspamd
- Global filters
parameters:
- name: kind
in: path
required: true
description: Kind of presets
schema:
type: string
enum:
- rspamd
- sieve
example: rspamd
responses:
"200":
description: List of presets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Preset"
example:
- name: preset_1
headline: Disable all but DKIM and rate limit for authenticated users
content: |-
priority = 10;
authenticated = yes;
apply "default" {
symbols_enabled = ["BCC", "DKIM_SIGNED", "RATELIMITED", "RATELIMIT_UPDATE", "RATELIMIT_CHECK", "DYN_RL_CHECK", "HISTORY_SAVE", "MILTER_HEADERS", "ARC_SIGNED"];
}
- name: preset_4
headline: Disable Rspamd for a domain
content: |-
priority = 10;
rcpt = "/.*@example.org$/";
from = "/.*/";
apply "default" {
MAILCOW_WHITE = -9999.0;
}
symbols [
"MAILCOW_WHITE"
]
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/global-filter:
post:
summary: Save a global Sieve filter
description: >-
Replaces the global Sieve prefilter or postfilter and restarts Dovecot.
A script with errors is not saved.
Messages: `global_filter_written`, `dovecot_restart_success`; errors
`sieve_error`, `invalid_filter_type`, `global_filter_write_error`,
`dovecot_restart_failed`.
operationId: addGlobalFilter
tags:
- Global filters
requestBody:
content:
application/json:
schema:
type: object
properties:
filter_type:
type: string
enum:
- prefilter
- postfilter
description: Which global filter to replace
script_data:
type: string
description: The Sieve script (CRLF and CR line ends become LF)
required:
- filter_type
- script_data
example:
filter_type: postfilter
script_data: |-
require "fileinto";
if header :contains "X-Spam-Flag" "YES" {
fileinto "Junk";
}
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/global_filters/all:
get:
summary: Get the global Sieve filters
description: >-
Returns the global Sieve prefilter and postfilter.
operationId: getGlobalFilters
tags:
- Global filters
responses:
"200":
description: Both scripts
content:
application/json:
schema:
$ref: "#/components/schemas/GlobalFilters"
example:
prefilter: |
# global_sieve_before script
# global_sieve_before -> user sieve_before (mailcow UI) -> user sieve_after (mailcow UI) -> global_sieve_after
postfilter: |-
# global_sieve_after script
require "fileinto";
if header :contains "X-Spam-Flag" "YES" {
fileinto "Junk";
}
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/global_filters/{filter_type}:
get:
summary: Get one global Sieve filter
description: >-
Returns the global Sieve prefilter or postfilter as a JSON string;
`{}` when the script is empty.
operationId: getGlobalFilter
tags:
- Global filters
parameters:
- name: filter_type
in: path
required: true
description: Which global filter
schema:
type: string
enum:
- prefilter
- postfilter
example: prefilter
responses:
"200":
description: The Sieve script
content:
application/json:
schema:
type: string
example: |
# global_sieve_before script
# global_sieve_before -> user sieve_before (mailcow UI) -> user sieve_after (mailcow UI) -> global_sieve_after
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/quota_notification:
post:
summary: Edit quota notification settings
description: >-
Saves sender, subject and template of the mails users get when their
mailbox crosses 80 % and 95 % of its quota. Fields not sent become
empty. The current values cannot be read through the API.
Messages: `saved_settings`; errors `redis_error`.
operationId: editQuotaNotification
tags:
- Quota notifications
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: Ignored
attr:
type: object
properties:
sender:
type: string
description: Sender address (invalid address = empty)
subject:
type: string
description: Subject
html_tmpl:
type: string
description: HTML template (empty = the default template)
required:
- attr
example:
items:
- quota_notification
attr:
sender: quota-warning@example.org
subject: Quota warning
html_tmpl: ""
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/quota_notification_bcc:
post:
summary: Edit quota notification BCC of a domain
description: >-
Sets the addresses that get a copy of every quota warning of a domain;
the list replaces the old one and cannot be read through the API.
Admins and domain admins of the domain. Invalid addresses are left out,
the others are saved.
Messages: `saved_settings`; errors `goto_invalid`, `redis_error`.
operationId: editQuotaNotificationBcc
tags:
- Quota notifications
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
description: Ignored
attr:
type: object
properties:
domain:
type: string
description: Domain or alias domain
bcc_rcpt:
type: string
description: Addresses, separated by space, comma, semicolon or newline
active:
type: [boolean, integer, string]
description: 1 = send the copies; becomes 0 when no valid address is left
required:
- domain
required:
- attr
example:
items:
- quota_bcc
attr:
domain: example.org
bcc_rcpt: |-
postmaster@example.org
helpdesk@example.org
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/admin/all:
get:
summary: Get administrators
description: Lists all administrators, without domain administrators and the API key account.
operationId: getAdmins
tags:
- Administrators
responses:
"200":
description: The administrators, `{}` if there are none
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Admin"
example:
- username: admin
tfa_active: 1
tfa_active_int: 1
active: 1
active_int: 1
created: "2026-09-21 10:23:08"
attributes:
force_tfa: "0"
force_pw_update: "0"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/admin/{username}:
get:
summary: Get administrator
description: Details of one administrator.
operationId: getAdmin
tags:
- Administrators
parameters:
- name: username
in: path
required: true
description: Username of the administrator
schema:
type: string
example: admin
responses:
"200":
description: The administrator, `{}` if there is no administrator of this name
content:
application/json:
schema:
$ref: "#/components/schemas/Admin"
example:
username: admin
tfa_active: 0
tfa_active_int: 0
active: 1
active_int: 1
created: "2026-09-21 10:23:08"
attributes:
force_tfa: "0"
force_pw_update: "0"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/add/admin:
post:
summary: Create administrator
description: >-
Creates an administrator. The username is stored in lowercase and must
not be in use by an administrator or domain administrator. Without
`active: 1` the account is disabled.
Messages: `admin_added`; errors `object_exists`, `password_complexity`,
`password_mismatch`.
operationId: addAdmin
tags:
- Administrators
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Username (letters, digits, `_`, `.`, `-`; stored in lowercase)
password:
type: string
description: Password, must match the password policy
password2:
type: string
description: The password again
active:
type: [integer, string, boolean]
description: 1 = the account can log in, 0 = disabled
default: 0
required:
- username
- password
- password2
example:
username: admin2
password: "Rand0m-Passw0rd!"
password2: "Rand0m-Passw0rd!"
active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/mail-policy:
post:
summary: Create mail policy
description: >-
Create a mail policy (admins; domain admins with the "mail_policies" ACL for their
domains). Postfix checks the policies for every recipient: every policy of the
sending mailbox and of the addressed mailbox or group must allow the mail, otherwise
the recipient is refused with 550 5.7.1.
operationId: addMailPolicy
tags:
- Mail policies
requestBody:
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
description: domain of the policy
type: string
name:
description: unique per domain, max. 100 characters
type: string
description:
description: max. 255 characters
type: string
send_mode:
description: >-
all; internal = recipients in the domain of the policy and its alias
domains plus send_allow; list = send_allow only
type: string
send_allow:
description: >-
addresses, domains or group:<id> of a group of the policy's domain
(array or list separated by commas, spaces or newlines), max. 500
type: array
send_block:
description: recipients that are always refused, entries as send_allow
type: array
receive_mode:
description: >-
all; internal = senders logged in with a mailbox of the domain plus
receive_allow; list = receive_allow only
type: string
receive_allow:
description: >-
entries as send_allow; addresses and domains of this mailcow count
for logged-in senders only
type: array
receive_block:
description: senders that are always refused, entries as receive_allow
type: array
reject_text:
description: >-
text of the 550 5.7.1 rejection, printable ASCII, max. 200 characters,
empty = default text
type: string
mailboxes:
description: >-
mailboxes of the domain the policy applies to (replaces the list),
max. 500
type: array
groups:
description: >-
group IDs of the domain the policy applies to (its members of that
domain and mail to the group address), max. 500; domain admins need
the mailbox_groups ACL, without it group IDs and group entries stay
unchanged
type: array
active:
type: boolean
example:
domain: example.org
name: Trainees
send_mode: internal
send_allow:
- partner.example
receive_mode: all
receive_block:
- group:8
groups:
- "7"
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/retention-rule:
post:
summary: Create retention rule
description: >-
Create a retention rule (admins; domain admins with the "retention" ACL for their
domains). Every night mail is deleted from the folders of the rule once it was
saved there more than "days" days ago. If several rules apply to the same folder
of a mailbox, the most specific one wins, per folder: mailbox before group before
domain, then the folder itself (special folder, inbox, own name) before an own
name with *, before the subfolders of a special folder or the inbox, before all
folders, then the longer period. New rules simulate by default. Rules of inactive
domains do not run.
operationId: addRetentionRule
tags:
- Retention rules
requestBody:
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
description: domain of the rule
type: string
name:
description: unique per domain, max. 100 characters
type: string
description:
description: max. 255 characters
type: string
folders:
description: >-
trash, junk, sent, drafts, archive, inbox (each with its subfolders),
all (folders no other rule decides about) and folder:<name> (exactly
this own folder, / for subfolders, * as wildcard), max. 50; replaces
the list
type: array
own_folders:
description: >-
own folder names, one per line or as a list, replacing the folder:<name>
entries (the UI sends them apart)
oneOf:
- type: string
- type: array
days:
description: >-
delete mail saved in the folder more than this many days ago, 1 to
36500
type: integer
keep_flagged:
description: flagged mail stays
type: boolean
mode:
description: simulate (the nightly run only counts, default) or delete
type: string
all_mailboxes:
description: applies to all mailboxes of the domain
type: boolean
mailboxes:
description: >-
mailboxes of the domain the rule applies to (replaces the list), max.
500
type: array
groups:
description: >-
group IDs of the domain (their members of that domain), max. 500;
domain admins need the mailbox_groups ACL, without it the groups stay
unchanged
type: array
active:
type: boolean
example:
domain: example.org
name: Trash
folders:
- trash
- junk
days: 30
keep_flagged: "1"
mode: simulate
all_mailboxes: "1"
active: "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/backup-job:
post:
summary: Create backup job
description: >-
Queue a job for the backup container (admins): backup (database dump, export of
the domains, restic backup, forget by the keep policy), check (restic check of
the structure and 1/N of the data), prune (forget and delete unused data) or init
(test the connection, create the repository if it does not exist). One job of
each type at a time (backup_job_active). Needs a complete target and repository
password (backup_not_configured); a backup also the confirmation that the repository
password is stored outside of mailcow (backup_password_not_confirmed). Follow
the job with get/backup-job/{id}.
operationId: addBackupJob
tags:
- Backup
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
description: backup, check, prune or init
type: string
example:
type: backup
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/add/backup-restore:
post:
summary: Create restore job
description: >-
Queue a restore from a snapshot (admins; domain admins for their domains). Scope
"mailbox" restores the given mailboxes of one domain, scope "domain" all mailboxes
of the domain; admins can also restore a deleted domain. Deleted mailboxes are
created from the backup first. The restore only adds what is missing, except "sogo",
"settings" and "password", which replace the current values with the backup's.
Components: mails (mail_target "folder": a copy below "Restored <snapshot time>";
"original": only missing messages, into their folders), imap_acl, aliases, groups,
sender_acl, mail_policies, retention_rules, filters, sieve_activate (needs filters),
spam, bcc, syncjobs, app_passwords, tfa, sogo, settings, password. Domain admins
need the matching ACL (else backup_component_denied). Snapshots made with RESTIC_BACKUP_MODE=config
hold no mails (backup_components_no_mails). Results per mailbox and component:
get/backup-job/{id}.
operationId: addBackupRestore
tags:
- Backup
requestBody:
content:
application/json:
schema:
type: object
properties:
snapshot:
description: id or short id of the snapshot (get/backup-snapshots)
type: string
scope:
description: >-
mailbox (the given mailboxes, default) or domain (all mailboxes of
the domain)
type: string
mailboxes:
description: >-
mailboxes of one domain, scope mailbox only, max. 1000; deleted ones
from the snapshot's content list are created
type: array
domain:
description: >-
the domain (required for scope domain, a deleted one for admins; for
scope mailbox it must exist and match the mailboxes)
type: string
components:
description: what to restore, see above
type: array
mail_target:
description: folder (default) or original
type: string
example:
snapshot: 3ee0b6f7
scope: mailbox
mailboxes:
- user@example.org
components:
- mails
- imap_acl
- aliases
- sender_acl
- filters
mail_target: folder
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/admin:
post:
summary: Edit administrators
description: >-
Changes administrators. Fields not sent keep their value, but
`force_tfa` and `force_pw_update` are reset to 0; an empty `password`
keeps the password. FIDO2 keys are not moved on rename. The last active
administrator cannot be deactivated.
Messages: `admin_modified`; errors `username_invalid`,
`password_mismatch`, `password_complexity`; warning `no_active_admin`.
operationId: editAdmin
tags:
- Administrators
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
description: Username of the administrator, or a list of usernames
oneOf:
- type: string
- type: array
items:
type: string
attr:
type: object
properties:
active:
type: [integer, string, boolean]
description: 1 = active, 0 = disabled
username_new:
type: string
description: New username (letters, digits, `_`, `.`, `-`)
password:
type: string
description: New password; empty or missing keeps the password
password2:
type: string
description: The new password again
force_tfa:
type: [integer, string, boolean]
description: 1 = the administrator must set up two-factor authentication at the next login
default: 0
force_pw_update:
type: [integer, string, boolean]
description: 1 = the administrator must change the password at the next login
default: 0
disable_tfa:
type: [integer, string, boolean]
description: Present (any value) = turn off two-factor authentication
required:
- items
- attr
example:
items:
- admin2
attr:
active: 1
password: "N3w-Passw0rd!"
password2: "N3w-Passw0rd!"
force_pw_update: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/admin:
post:
summary: Delete administrators
description: >-
Deletes administrators with their two-factor authentication and FIDO2
keys.
Messages: `admin_removed`; error `username_invalid`.
operationId: deleteAdmin
tags:
- Administrators
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Usernames of the administrators
items:
type: string
example:
- admin2
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/mail-policy:
post:
summary: Delete mail policies
description: Delete mail policies by ID.
operationId: deleteMailPolicies
tags:
- Mail policies
requestBody:
content:
application/json:
schema:
type: array
description: Policy ids
items:
type:
- integer
- string
example:
- "3"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/retention-rule:
post:
summary: Delete retention rules
description: Delete retention rules by ID.
operationId: deleteRetentionRules
tags:
- Retention rules
requestBody:
content:
application/json:
schema:
type: array
description: Rule ids
items:
type:
- integer
- string
example:
- "3"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/delete/backup-job:
post:
summary: Cancel backup jobs
description: >-
Cancel backup jobs by ID (admins any job, domain admins the restores of their
domains). Queued jobs and running jobs can be cancelled, except a restore while
the dovecot container restores the mails (step mails or mails_running; backup_job_not_cancellable).
A running job stops at its next check; what it restored so far stays. One message
per ID.
operationId: cancelBackupJobs
tags:
- Backup
requestBody:
content:
application/json:
schema:
type: array
description: Job ids
items:
type:
- integer
- string
example:
- 12
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/get/passwordpolicy:
get:
summary: Get password policy
description: The password policy for mailboxes, administrators and domain administrators.
operationId: getPasswordPolicy
tags:
- Password policy
responses:
"200":
description: The policy
content:
application/json:
schema:
$ref: "#/components/schemas/PasswordPolicy"
example:
length: "8"
chars: "1"
special_chars: "0"
lowerupper: "1"
numbers: "1"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/passwordpolicy/html:
get:
summary: Get password policy as HTML
description: >-
The password policy as HTML snippet in the default language, as shown
below password fields.
operationId: getPasswordPolicyHtml
tags:
- Password policy
responses:
"200":
description: The HTML snippet as a JSON string
content:
application/json:
schema:
type: string
example: <p class="help-block small">- Minimum password length is 8<br>- Must contain at least one alphabetic character<br>- Must contain lowercase and uppercase characters<br>- Must contain at least one number</p>
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/logs/retention/{count}":
get:
summary: Get retention logs
description: >-
Results of the nightly retention runs of the last 90 days, newest first: mailboxes
with found mail or an error, per mailbox and rule (folder: the folder names separated
by line breaks); of simulating rules only the last run. Admins see all domains
and one row per run (rule_id null, username empty, error if the run failed), domain
admins with the "retention" ACL their domains.
operationId: getRetentionLogs
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: Number of logs to return (default 1000)
schema:
type: integer
example: 100
responses:
"200":
description: Retention logs
content:
application/json:
schema:
type: array
items:
type: object
example:
- time: "1794368412"
domain: example.org
username: user@example.org
rule_id: 3
rule_name: Trash
folder: "Trash\nTrash/Old"
days: 30
mailboxes: 0
matched: 12
deleted: 12
errors: 0
simulated: 0
error: null
- time: "1794368400"
domain: ""
username: ""
rule_id: null
rule_name: ""
folder: null
days: 0
mailboxes: 120
matched: 4211
deleted: 312
errors: 0
simulated: 0
error: null
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/mail-policy/{id}":
get:
summary: Get mail policies
description: >-
Mail policies visible to the caller (admins all, domain admins with the "mail_policies"
ACL their domains).
operationId: getMailPolicies
tags:
- Mail policies
parameters:
- name: id
in: path
required: true
description: id of the policy, or "all" (optionally followed by /domain1,domain2)
schema:
type: string
example: all
responses:
"200":
description: Mail policies
content:
application/json:
schema:
type: array
items:
type: object
example:
- id: 3
domain: example.org
name: Trainees
description: Trainees only send internally
send_mode: internal
send_allow:
- partner.example
send_block: []
receive_mode: all
receive_allow: []
receive_block:
- group:8
reject_text: ""
active: 1
mailboxes: []
groups:
- 7
created: "2026-11-07 12:00:00"
modified: null
can_edit: 1
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/mail-policy/test/{sender}/{recipient}":
get:
summary: Test mail policies
description: >-
Would Postfix accept the mail for this recipient? side is "send", "receive" or
"address" (the recipient routes through another address), policy is empty for
a policy of another domain (its text is then the default text), internal_alias
= refused by the internal flag of an alias or group. Domain admins test addresses
of their domains; a sender of another domain is tested as not logged in. Empty
answer for invalid input.
operationId: testMailPolicies
tags:
- Mail policies
parameters:
- name: sender
in: path
required: true
description: envelope sender, "-" for the null sender (bounces)
schema:
type: string
example: trainee@example.org
- name: recipient
in: path
required: true
description: recipient; append /login to test a sender logged in with its mailbox
schema:
type: string
example: someone@external.example
responses:
"200":
description: Test mail policies
content:
application/json:
schema:
type: object
example:
allowed: 0
side: send
policy: Trainees
internal_alias: 0
logged_in: 1
text: >-
Sending to this recipient is not allowed by the mail policy of the sender
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/retention-rule/{id}":
get:
summary: Get retention rules
description: >-
Retention rules visible to the caller (admins all, domain admins with the "retention"
ACL their domains), with the summary of their last nightly run (null = not run
yet).
operationId: getRetentionRules
tags:
- Retention rules
parameters:
- name: id
in: path
required: true
description: id of the rule, or "all" (optionally followed by /domain1,domain2)
schema:
type: string
example: all
responses:
"200":
description: Retention rules
content:
application/json:
schema:
type: array
items:
type: object
example:
- id: 3
domain: example.org
name: Trash
description: ""
folders:
- trash
days: 30
keep_flagged: 0
mode: delete
all_mailboxes: 1
active: 1
mailboxes: []
groups: []
created: "2026-11-07 12:00:00"
modified: null
can_edit: 1
last_run:
created: "2026-11-08 03:30:12"
mailboxes: 120
matched: 4211
deleted: 4211
errors: 0
simulated: 0
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/retention-rule/effective/{username}":
get:
summary: Get effective retention rules
description: >-
What the rules delete in a mailbox, in order of "most specific wins": each folder
of the mailbox goes to the first entry that matches it. match: folder (the folder
itself), pattern (own name with *), subfolders (of a special folder or the inbox),
all. Mailbox users ask for their own mailbox, admins and domain admins with the
"retention" ACL for mailboxes they manage.
operationId: getEffectiveRetentionRules
tags:
- Retention rules
parameters:
- name: username
in: path
required: true
description: mailbox
schema:
type: string
example: user@example.org
responses:
"200":
description: Effective retention rules
content:
application/json:
schema:
type: array
items:
type: object
example:
- folder: trash
match: folder
days: 30
keep_flagged: 0
mode: delete
rule_id: 3
rule_name: Trash
- folder: trash
match: subfolders
days: 30
keep_flagged: 0
mode: delete
rule_id: 3
rule_name: Trash
- folder: all
match: all
days: 365
keep_flagged: 1
mode: simulate
rule_id: 4
rule_name: One year
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/backup-settings:
get:
summary: Get backup settings
description: >-
The backup settings (admins, also read-only API keys). Secrets are never returned,
password_set, s3_secret_key_set and rest_password_set tell whether they are set.
sftp_public_key (add it to the authorized_keys of the SFTP user), sftp_host_key
and the state_* values are written by the backup container. configured: target
and repository password are complete. {} for everybody else.
operationId: getBackupSettings
tags:
- Backup
responses:
"200":
description: Backup settings
content:
application/json:
schema:
type: object
example:
enabled: 1
target: sftp
s3_endpoint: https://s3.amazonaws.com
s3_bucket: ""
s3_path: ""
s3_region: ""
s3_access_key: ""
s3_secret_key_set: 0
s3_path_style: 0
sftp_host: backup.example.org
sftp_port: 22
sftp_user: mailcow
sftp_path: backups/mailcow
sftp_public_key: >-
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... mailcow-backup@mail.example.org
sftp_host_key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
rest_url: ""
rest_user: ""
rest_password_set: 0
local_path: mailcow
password_set: 1
password_confirmed: 1
schedule:
- days:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
time: 02:30
keep_hourly: 0
keep_daily: 14
keep_weekly: 4
keep_monthly: 12
keep_yearly: 0
prune_weekday: 0
max_unused: 10%
check_subset: 30
include_index: 1
include_fts: 1
limit_upload: 0
notify_email: admin@example.org
state_initialized: 1
state_runner_seen: 1794093697
state_last_backup: 6
state_last_success: 1794089278
state_repo_size: 84418594
state_repo_stats:
total_size: 84418594
snapshots_count: 2
configured: 1
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/backup-status:
get:
summary: Get backup status
description: >-
State of the backup (admins): configuration, heartbeat of the backup container
(runner_ok: reported within the last 120 seconds), last successful backup, repository
size, number of snapshots, the next scheduled run (null while the schedule is
off or waits for the password confirmation), schedule_gap (the longest time between
two scheduled backups in seconds; a last success older than that is overdue),
the newest job of each type and the queued and running jobs. secrets_error (null
when fine): the backup container cannot decrypt the stored secrets (e.g. after
the database was restored on another server); enter the repository password and
the credentials again. mode: RESTIC_BACKUP_MODE of mailcow.conf (all, data or
config; null until the backup container reported it). Times are unix timestamps.
operationId: getBackupStatus
tags:
- Backup
responses:
"200":
description: Backup status
content:
application/json:
schema:
type: object
example:
enabled: 1
target: local
configured: 1
password_confirmed: 1
initialized: 1
runner_seen: 1794094257
runner_age: 4
runner_ok: 1
last_success: 1794089278
repo_size: 84418594
repo_stats:
total_size: 84418594
snapshots_count: 2
snapshots: 2
latest_snapshot: 1794089277
next_run: 1794101400
schedule_gap: 86400
secrets_error: null
mode: all
jobs:
backup:
id: 26
type: backup
state: done
step: null
params: {}
result:
snapshot: f4f5a5fec226eec1cdd8ddd8f02b1fe8e6a1441ce130c507ca877f8b26a0bb3e
error: null
domain: ""
requested_by: schedule
created: 1794093646
started: 1794093646
finished: 1794093653
check: null
prune: null
init: null
restore: null
active: []
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/backup-snapshots:
get:
summary: Get backup snapshots
description: >-
The snapshots in the repository, newest first, as of the last backup or prune
(admins). Domain admins get the snapshots that hold one of their domains and were
made after the domain was created, with id, short_id, time, mode and those domains
only. domains is null for snapshots not made by mailcow. mode: what the backup
holds, from RESTIC_BACKUP_MODE (tag mode:<mode>): all, data (without the mailcow
directory) or config (without mails).
operationId: getBackupSnapshots
tags:
- Backup
responses:
"200":
description: Backup snapshots
content:
application/json:
schema:
type: array
items:
type: object
example:
- id: 3ee0b6f795f9e7bebf4274758147ddc593f81f6925db82f6eaf0029f71dcc71f
short_id: 3ee0b6f7
time: 1794089277
hostname: mail.example.org
tags:
- mailcow
summary:
files_new: 104
files_changed: 24
data_added: 4103499
total_bytes_processed: 92154276
domains:
- example.org
mode: all
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-snapshot-content/{snapshot}":
get:
summary: Get backup snapshot content
description: >-
The domains of a snapshot with their state now: exists (the domain exists now),
mailboxes (in the snapshot) and missing (of them deleted now). Admins get all
domains, domain admins the domains they administer now (snapshots made after the
domain was created). available 0: the snapshot has no content list (made before
mailcow kept one), the list then comes from its manifest and counts the mailboxes
that exist now; only those can be restored. {} if the snapshot does not exist
or is not visible.
operationId: getBackupSnapshotContent
tags:
- Backup
parameters:
- name: snapshot
in: path
required: true
description: id or short id of the snapshot
schema:
type: string
example: 3ee0b6f7
responses:
"200":
description: Backup snapshot content
content:
application/json:
schema:
type: object
example:
snapshot: 3ee0b6f795f9e7bebf4274758147ddc593f81f6925db82f6eaf0029f71dcc71f
time: 1794089277
available: 1
domains:
- domain: example.org
exists: 1
mailboxes: 42
missing: 2
- domain: old.example.org
exists: 0
mailboxes: 5
missing: 5
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-snapshot-content/{snapshot}/{domain}":
get:
summary: Get backup snapshot domain content
description: >-
The mailboxes of a domain in a snapshot with their state now (exists 0: deleted
since, a restore creates it from the backup). Same visibility as get/backup-snapshot-content/{snapshot};
{} if not visible.
operationId: getBackupSnapshotDomainContent
tags:
- Backup
parameters:
- name: snapshot
in: path
required: true
description: id or short id of the snapshot
schema:
type: string
example: 3ee0b6f7
- name: domain
in: path
required: true
description: a domain of the snapshot
schema:
type: string
example: example.org
responses:
"200":
description: Backup snapshot domain content
content:
application/json:
schema:
type: object
example:
domain: example.org
exists: 1
mailboxes:
- username: info@example.org
name: Info
exists: 1
- username: former@example.org
name: Former Colleague
exists: 0
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-snapshot-search/{snapshot}/{term}":
get:
summary: Search backup snapshot
description: >-
Search the domains and mailboxes of a snapshot (case-insensitive "contains").
A plain term matches the domain name, the local part, the full address or the
display name; a matching domain comes with all its mailboxes. "x@" matches the
local part only, "@d" returns all mailboxes of the matching domains (a matching
domain also appears without mailboxes), "x@d" matches the full address only. An
empty term or "@" returns no domains. At most 500 mailboxes, then truncated is
1. Same visibility as get/backup-snapshot-content (domain admins: domains they
administer, snapshots made after the domain was created); {} when the snapshot
does not exist or is not visible. For snapshots without a content list the current
mailboxes of the snapshot's domains are searched. The path is decoded before json_api.php
reads it: encode the term twice when it may contain "&", "+", "%" or "#" (the
UI always encodes it twice).
operationId: searchBackupSnapshot
tags:
- Backup
parameters:
- name: snapshot
in: path
required: true
description: id or short id of the snapshot
schema:
type: string
example: 3ee0b6f7
- name: term
in: path
required: true
description: search term, URL-encoded (path segment)
schema:
type: string
example: carol
responses:
"200":
description: Search backup snapshot
content:
application/json:
schema:
type: object
example:
domains:
- domain: example.org
exists: 0
mailboxes:
- username: carol@example.org
name: Carol
exists: 0
truncated: 0
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-jobs/{count}":
get:
summary: Get backup jobs
description: >-
Backup jobs without their log, newest first: admins all jobs, domain admins the
restores of their domains. state: queued, running, done, failed or cancelled;
step: what a running job does. The result of a restore holds per mailbox and component
the numbers of added and already existing (skipped) entries and the errors; "mailbox"
tells whether a deleted mailbox was created, "domain" (next to "mailboxes") the
creation of a deleted domain. Finished jobs are kept for 180 days.
operationId: getBackupJobs
tags:
- Backup
parameters:
- name: count
in: path
required: true
description: >-
Number of jobs to return, newest first (default 100 without this part, max.
1000)
schema:
type: integer
example: 100
responses:
"200":
description: Backup jobs
content:
application/json:
schema:
type: array
items:
type: object
example:
- id: 12
type: restore
state: done
step: null
params:
snapshot: 3ee0b6f795f9e7bebf4274758147ddc593f81f6925db82f6eaf0029f71dcc71f
snapshot_time: 1794089277
scope: mailbox
domain: example.org
mailboxes:
- user@example.org
components:
- mails
- aliases
mail_target: folder
requested_role: admin
create_domain: 0
create_mailboxes:
- user@example.org
result:
snapshot:
id: 3ee0b6f795f9e7bebf4274758147ddc593f81f6925db82f6eaf0029f71dcc71f
short_id: 3ee0b6f7
time: 2026-11-07 23:07
mailboxes:
user@example.org:
mailbox:
added: 1
created: 1
mails:
added: 32
skipped: 0
errors: []
folder: Restored 2026-11-07 23:07
aliases:
added: 1
skipped: 2
errors: []
errors: 0
error: null
domain: example.org
requested_by: admin
created: 1794094015
started: 1794094016
finished: 1794094062
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-jobs/{count}/{type}":
get:
summary: Get backup jobs of a type
description: >-
Backup jobs of one type without their log, newest first, with the visibility of
get/backup-jobs/{count} (domain admins: the restores of their domains). E.g. get/backup-jobs/0/restore
for the restores.
operationId: getBackupJobsByType
tags:
- Backup
parameters:
- name: count
in: path
required: true
description: Number of jobs to return, newest first; 0 = 100, max. 1000
schema:
type: integer
example: 0
- name: type
in: path
required: true
description: >-
only jobs of this type (backup, check, prune, init or restore); an unknown
type returns []
schema:
type: string
example: restore
responses:
"200":
description: Backup jobs of a type
content:
application/json:
schema:
type: array
items:
type: object
example:
- id: 12
type: restore
state: done
step: null
params:
snapshot: 3ee0b6f795f9e7bebf4274758147ddc593f81f6925db82f6eaf0029f71dcc71f
scope: mailbox
domain: example.org
mailboxes:
- user@example.org
components:
- mails
mail_target: folder
result: null
error: null
domain: example.org
requested_by: admin
created: 1794094015
started: 1794094016
finished: 1794094062
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/backup-job/{id}":
get:
summary: Get backup job
description: >-
A backup job with its log (the same entry as in get/backup-jobs plus "log"). {}
if the job does not exist or the caller may not see it.
operationId: getBackupJob
tags:
- Backup
parameters:
- name: id
in: path
required: true
description: id of the job
schema:
type: integer
example: 12
responses:
"200":
description: Backup job
content:
application/json:
schema:
type: object
example:
id: 11
type: backup
state: done
step: null
params: {}
result:
dump_bytes: 667156
export:
domains: 1
failed: []
snapshot: f4f5a5fec226eec1cdd8ddd8f02b1fe8e6a1441ce130c507ca877f8b26a0bb3e
summary:
files_new: 1696
files_changed: 0
data_added: 93096838
total_bytes_processed: 95911108
forget:
removed: 0
snapshots: 3
error: null
domain: ""
requested_by: schedule
created: 1794093646
started: 1794093646
finished: 1794093653
log: "2026-11-08 02:30:01 backup job started (requested by schedule)\n\
2026-11-08 02:30:03 snapshot f4f5a5fe: 1696 new and 0 changed files,\
\ 88 MiB added, 91 MiB processed\n2026-11-08 02:30:07 backup job done"
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/archive/mailboxes:
get:
summary: Get archived mailboxes
description: >-
Mailboxes whose mails go to the archive now (admins, read-only keys included).
A mailbox is archived when archiving is switched on (`enabled`) and its setting
is `1`, or `inherit` while its domain archives by default (`source` says which).
Only mailboxes that receive mail are listed: `active` 1, or 2 (no login, mail
is delivered). `username` is the value of the X-Archive-Owner header. Mailboxes
that drop out of the list (archiving switched off, deleted, renamed) keep their
mails in the archive.
operationId: getArchivedMailboxes
tags:
- Archive
responses:
"200":
description: Archived mailboxes
content:
application/json:
schema:
type: object
example:
enabled: 1
mailboxes:
- username: anna@example.org
domain: example.org
name: Anna Example
active: 1
source: domain
- username: board@example.net
domain: example.net
name: Board
active: 2
source: mailbox
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/archive/status:
get:
summary: Get archive status
description: >-
Summary of the archive state (admins, read-only keys included): copies waiting
in the Postfix queue with the reasons Postfix gives, the time of the last delivery
to the archive, and mails that were not archived because their copy could not
be handed to Postfix (`dropped` since ever, `dropped_24h` and `last_dropped` for
the last 24 hours).
operationId: getArchiveStatus
tags:
- Archive
responses:
"200":
description: Archive status
content:
application/json:
schema:
type: object
example:
enabled: 1
configured: 1
queued: 2
queued_bytes: 182044
oldest_queued: 1762425600
delay_reasons:
- "connect to archive.example.org[192.0.2.10]:25: Connection refused"
last_delivery: 1762425580
dropped: 3
dropped_24h: 1
last_dropped:
time: 1762425500
reason: owner lookup failed (nil, 502)
"401":
$ref: "#/components/responses/Unauthorized"
"/api/v1/get/logs/archive/{count}":
get:
summary: Get archive log
description: >-
Archive log, newest first (admins, read-only keys included): deliveries of copies
from the Postfix log (`status` sent, deferred, softbounce when the archive refused
the copy and Postfix keeps it, or bounced), copies discarded after the queue lifetime
(expired) and mails that were not archived (dropped, `text` is the reason). `message_id`
is the Message-ID of the mail, `qid` the queue ID of the copy (of the mail for
dropped). Tip: You can limit how many logs you want to get by using `/<count>`
at the end of the api url.
operationId: getArchiveLogs
tags:
- Logs
parameters:
- name: count
in: path
required: true
description: Number of logs to return
schema:
type: integer
example: 100
responses:
"200":
description: Archive log
content:
application/json:
schema:
type: array
items:
type: object
example:
- time: 1762425580
status: sent
qid: 4XyZ1abc
message_id: c3d1e0f2@example.org
text: "250 2.0.0 Ok: queued as 9F2C4"
- time: 1762425500
status: dropped
qid: 3AbC2def
message_id: a1b2c3@example.org
text: owner lookup failed (nil, 502)
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/get/archive/settings:
get:
summary: Get archive settings
description: >-
Archive target (admins, read-only keys included); password and signing key are
never returned.
operationId: getArchiveSettings
tags:
- Archive
responses:
"200":
description: Archive settings
content:
application/json:
schema:
type: object
example:
enabled: 1
address: journal@archive.example.org
host: archive.example.org
port: 25
tls: encrypt
username: ""
has_password: 0
profile: archivecow
has_signing_secret: 1
header_from: X-Envelope-From
header_rcpt: X-Envelope-To
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/edit/passwordpolicy:
post:
summary: Edit password policy
description: >-
Changes the password policy; fields not sent keep their value. Existing
passwords are not checked again.
Messages: `password_policy_saved`.
operationId: editPasswordPolicy
tags:
- Password policy
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
length:
type: [integer, string]
description: Minimum length; values below 3 keep the current length
chars:
type: [integer, string, boolean]
description: 1 = at least one letter
lowerupper:
type: [integer, string, boolean]
description: 1 = lowercase and uppercase letters
special_chars:
type: [integer, string, boolean]
description: 1 = at least one character that is no letter or digit
numbers:
type: [integer, string, boolean]
description: 1 = at least one digit
required:
- attr
example:
attr:
length: 12
chars: 1
lowerupper: 1
special_chars: 0
numbers: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/reset-password-notification:
post:
summary: Edit password reset e-mail
description: >-
Sets the password reset e-mail sent to the recovery address of a
mailbox. Fields not sent are saved as empty. With both templates empty
the defaults are used; without sender and subject, password reset is
off.
Placeholders: `{{username}}`, `{{username2}}` (recovery address),
`{{date}}`, `{{token_lifetime}}` (minutes), `{{hostname}}`, `{{link}}`.
Messages: `saved_settings`.
operationId: editPasswordResetNotification
tags:
- Password policy
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
from:
type: string
description: Sender address; an invalid address is saved as empty
subject:
type: string
description: Subject
text_tmpl:
type: string
description: Plain text template
html_tmpl:
type: string
description: HTML template (the text template becomes its alternative part)
required:
- attr
example:
attr:
from: noreply@example.org
subject: Reset your password
text_tmpl: "Hello {{username}}, open {{link}} within {{token_lifetime}} minutes to set a new password."
html_tmpl: "<p>Hello {{username}},</p><p><a href=\"{{link}}\">Set a new password</a> within {{token_lifetime}} minutes.</p>"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/app_links:
post:
summary: Edit app links
description: >-
Replaces the custom links of the Apps menu, sent as four lists of equal
length. If the lengths differ, nothing is saved, but `app_links` is
reported anyway. Empty lists remove all custom links.
Messages: `app_links`.
operationId: editAppLinks
tags:
- UI customization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
app:
type: array
description: Names of the links
items:
type: string
href:
type: array
description: URLs shown on the login page and to users without `user_href`
items:
type: string
user_href:
type: array
description: URLs for logged-in accounts (`%u` = username); empty = `href`
items:
type: string
hide:
type: array
description: Per link, `0` shows it on the login page, any other value (even `false`) hides it
items:
type: [string, integer, boolean]
required:
- attr
example:
attr:
app:
- Wiki
- Webmail (Roundcube)
href:
- https://wiki.example.org
- https://mail.example.org/rc/
user_href:
- https://wiki.example.org
- https://mail.example.org/rc/?_user=%u
hide:
- "0"
- "1"
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/custom_login:
post:
summary: Edit login page options
description: >-
Sets the login page options. All four are replaced: a missing option
counts as 0.
Messages: `custom_login_modified`.
operationId: editCustomLogin
tags:
- UI customization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
hide_user_quicklink:
type: [integer, string, boolean]
description: 1 = hide the link to the user login page
default: 0
hide_domainadmin_quicklink:
type: [integer, string, boolean]
description: 1 = hide the link to the domain administrator login page
default: 0
hide_admin_quicklink:
type: [integer, string, boolean]
description: 1 = hide the link to the administrator login page
default: 0
force_sso:
type: [integer, string, boolean]
description: 1 = show only the Single Sign-On button (needs an OIDC identity provider)
default: 0
required:
- attr
example:
attr:
hide_user_quicklink: 0
hide_domainadmin_quicklink: 1
hide_admin_quicklink: 1
force_sso: 0
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/ip_check:
post:
summary: Edit IP check
description: >-
Turns the dashboard IP check on or off, which asks ipv4.mailcow.email
and ipv6.mailcow.email for the public addresses.
Messages: `ip_check_opt_in_modified`.
operationId: editIpCheck
tags:
- UI customization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
ip_check_opt_in:
type: [integer, string, boolean]
description: 1/true = enabled; anything else or missing = disabled
default: 0
required:
- attr
example:
attr:
ip_check_opt_in: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/ui_texts:
post:
summary: Edit UI texts
description: >-
Sets the texts of the mailcow UI. All values are replaced: a missing
one is saved as empty.
Messages: `ui_texts`.
operationId: editUiTexts
tags:
- UI customization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
title_name:
type: string
description: Title of the browser window (plain text); empty = "<hostname> - mail UI"
main_name:
type: string
description: Name shown on the start page (plain text); empty = "<hostname> - mail UI"
apps_name:
type: string
description: Name of the "Apps" menu (plain text); empty = "Apps"
help_text:
type: string
description: Help text below the login form (HTML)
ui_footer:
type: string
description: Footer of every page (HTML)
ui_announcement_text:
type: string
description: Announcement for all logged-in accounts and on the login page (HTML)
ui_announcement_type:
type: string
enum:
- info
- warning
- danger
description: Style of the announcement; other values are saved as empty
ui_announcement_active:
type: [integer, string, boolean]
description: Not empty and not 0 = show the announcement
default: 0
required:
- attr
example:
attr:
title_name: Example Mail
main_name: Example Mail
apps_name: Apps
help_text: "Questions? Write to <a href=\"mailto:support@example.org\">support@example.org</a>."
ui_footer: "<a href=\"https://example.org/imprint\">Imprint</a>"
ui_announcement_text: Maintenance on Saturday from 8 to 10 am.
ui_announcement_type: warning
ui_announcement_active: 1
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/ui_theme:
post:
summary: Edit UI theme
description: >-
Selects the UI theme by its folder name in `data/web/css/themes/`.
Messages: `ui_theme_modified`; error `ui_theme_invalid`.
operationId: editUiTheme
tags:
- UI customization
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
attr:
type: object
properties:
ui_theme:
description: Folder name of the theme, empty = default theme; of a list only the first entry counts
oneOf:
- type: string
- type: array
items:
type: string
required:
- attr
example:
attr:
ui_theme: servercow
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/mail-policy:
post:
summary: Update mail policies
description: >-
Update mail policies. Attributes you do not send keep their value. The domain
cannot be changed.
operationId: editMailPolicies
tags:
- Mail policies
requestBody:
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
attr:
properties:
name:
description: unique per domain, max. 100 characters
type: string
description:
description: max. 255 characters
type: string
send_mode:
description: >-
all; internal = recipients in the domain of the policy and its
alias domains plus send_allow; list = send_allow only
type: string
send_allow:
description: >-
addresses, domains or group:<id> of a group of the policy's domain
(array or list separated by commas, spaces or newlines), max.
500
type: array
send_block:
description: recipients that are always refused, entries as send_allow
type: array
receive_mode:
description: >-
all; internal = senders logged in with a mailbox of the domain
plus receive_allow; list = receive_allow only
type: string
receive_allow:
description: >-
entries as send_allow; addresses and domains of this mailcow count
for logged-in senders only
type: array
receive_block:
description: senders that are always refused, entries as receive_allow
type: array
reject_text:
description: >-
text of the 550 5.7.1 rejection, printable ASCII, max. 200 characters,
empty = default text
type: string
mailboxes:
description: >-
mailboxes of the domain the policy applies to (replaces the list),
max. 500
type: array
groups:
description: >-
group IDs of the domain the policy applies to (its members of
that domain and mail to the group address), max. 500; domain admins
need the mailbox_groups ACL, without it group IDs and group entries
stay unchanged
type: array
active:
type: boolean
type: object
items:
type: array
description: Policy ids
items:
type:
- integer
- string
example:
items:
- "3"
attr:
receive_mode: internal
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/retention-rule:
post:
summary: Update retention rules
description: >-
Update retention rules. Attributes you do not send keep their value. The domain
cannot be changed.
operationId: editRetentionRules
tags:
- Retention rules
requestBody:
content:
application/json:
schema:
type: object
required:
- items
- attr
properties:
attr:
properties:
name:
description: unique per domain, max. 100 characters
type: string
description:
description: max. 255 characters
type: string
folders:
description: >-
trash, junk, sent, drafts, archive, inbox (each with its subfolders),
all (folders no other rule decides about) and folder:<name> (exactly
this own folder, / for subfolders, * as wildcard), max. 50; replaces
the list
type: array
own_folders:
description: >-
own folder names, one per line or as a list, replacing the folder:<name>
entries (the UI sends them apart)
oneOf:
- type: string
- type: array
days:
description: >-
delete mail saved in the folder more than this many days ago,
1 to 36500
type: integer
keep_flagged:
description: flagged mail stays
type: boolean
mode:
description: simulate (the nightly run only counts, default) or
delete
type: string
all_mailboxes:
description: applies to all mailboxes of the domain
type: boolean
mailboxes:
description: >-
mailboxes of the domain the rule applies to (replaces the list),
max. 500
type: array
groups:
description: >-
group IDs of the domain (their members of that domain), max. 500;
domain admins need the mailbox_groups ACL, without it the groups
stay unchanged
type: array
active:
type: boolean
type: object
items:
type: array
description: Rule ids
items:
type:
- integer
- string
example:
items:
- "3"
attr:
mode: delete
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/backup-settings:
post:
summary: Update backup settings
description: >-
Save the backup settings (admins). Settings you do not send keep their value.
Secrets (password, s3_secret_key, rest_password) are write-only: an empty value
keeps the stored one. A new repository password resets password_confirmed unless
the same request confirms it. Secrets are stored encrypted with the public key
of the backup container (sealed box); until the container has published its key,
saving a secret fails with backup_secrets_key_missing. A new repository password
only works for a new repository (restic keeps the password a repository was created
with). Changing the target, its connection or the password makes the backup container
test the repository again; changing the SFTP host or port forgets the host key.
enabled needs a complete target and repository password (backup_not_configured).
Invalid values are refused with backup_setting_invalid and the name of the setting;
nothing is saved then.
operationId: editBackupSettings
tags:
- Backup
requestBody:
content:
application/json:
schema:
type: object
properties:
attr:
properties:
enabled:
description: back up at the times of schedule (needs at least one
entry)
type: boolean
target:
description: s3, sftp, rest or local
type: string
s3_endpoint:
description: http(s) URL of the S3 endpoint
type: string
s3_bucket:
type: string
s3_path:
description: path in the bucket (optional)
type: string
s3_region:
description: optional
type: string
s3_access_key:
type: string
s3_secret_key:
description: write-only
type: string
s3_path_style:
description: path-style bucket access (restic -o s3.bucket-lookup=path)
type: boolean
sftp_host:
type: string
sftp_port:
type: integer
sftp_user:
type: string
sftp_path:
description: >-
directory of the repository, relative to the home directory or
absolute
type: string
rest_url:
description: >-
URL of the restic REST server without credentials, e.g. https://backup.example.org:8000/mailcow
type: string
rest_user:
type: string
rest_password:
description: write-only
type: string
local_path:
description: subdirectory below RESTIC_LOCAL_PATH (default ./data/restic),
no ".."
type: string
password:
description: restic repository password, at least 8 characters,
write-only
type: string
password_confirmed:
description: >-
the admin confirms that the repository password is stored outside
of mailcow; backups need it
type: boolean
schedule:
description: >-
the scheduled backups, up to 24 entries (also as a JSON string);
each backs up on its weekdays at its time
type: array
items:
type: object
properties:
days:
description: weekdays, 0 (Sunday) to 6, at least one
type: array
items:
type: number
time:
description: HH:MM in the time zone of mailcow
type: string
keep_hourly:
description: hourly snapshots to keep (for several backups a day),
0 to 1000
type: integer
keep_daily:
description: daily snapshots to keep, 0 to 1000
type: integer
keep_weekly:
type: integer
keep_monthly:
type: integer
keep_yearly:
type: integer
prune_weekday:
description: >-
0 (Sunday) to 6, prune once a week after the first scheduled backup
from that day on; empty string = never (manual prune jobs only,
e.g. for append-only or object-lock targets)
oneOf:
- type: number
- type: string
max_unused:
description: restic prune --max-unused, 0% to 100%
type: string
check_subset:
description: >-
after the first scheduled backup of a day check 1/N of the data
(0 = off), 0 to 365
type: integer
include_index:
description: back up the Dovecot index
type: boolean
include_fts:
description: include the full-text search index (with include_index)
type: boolean
limit_upload:
description: KiB/s, 0 = unlimited
type: integer
notify_email:
description: >-
addresses separated by commas that get a mail when a job fails,
max. 20
type: string
type: object
items:
description: contains ["settings"]
type: object
example:
items:
- settings
attr:
enabled: "1"
target: s3
s3_endpoint: https://s3.eu-central-1.amazonaws.com
s3_bucket: mailcow-backup
s3_access_key: AKIAEXAMPLE
s3_secret_key: secret
password: a-long-repository-password
password_confirmed: "1"
schedule:
- days:
- 1
- 3
time: "12:00"
- days:
- 5
- 6
- 0
time: "18:00"
keep_daily: 14
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/api/v1/edit/archive:
post:
summary: Edit archive settings
description: >-
Archive target, admins with a read-write key only. mailcow sends a copy of every
accepted mail of archived mailboxes by SMTP to `address`, through the Postfix
queue (envelope sender `archive-bounce@localhost`, notices to it are dropped:
no bounce or delay warning reaches a sender). Attributes missing in the request
keep their value, an empty `password` or `signing_secret` keeps the stored one.
Switching on needs the address, and the signing key for the profile archivecow.
With `action: test` the stored target is tested (connection, TLS, AUTH, whether
the address is accepted; no mail is sent), with `action: testmail` a test copy
is sent through the mail queue.
operationId: editArchiveSettings
tags:
- Archive
requestBody:
content:
application/json:
schema:
type: object
properties:
items:
type: array
default:
- archive
attr:
type: object
properties:
enabled:
description: >-
copies of accepted mails go to the archive; copies already queued
are delivered either way
type: boolean
address:
description: address the archive receives copies at
type: string
host:
description: SMTP server of the archive, empty for the MX of the
address domain
type: string
port:
type: integer
default: 25
tls:
description: >-
`encrypt` (TLS required), `verify` (TLS required, certificate
verified), `may`
type: string
enum:
- encrypt
- verify
- may
username:
description: SMTP AUTH user at the archive, empty for none
type: string
password:
description: SMTP AUTH password, never returned
type: string
profile:
description: >-
headers in front of each copy: `archivecow` (X-Archive-Owner,
-Rcpt, -From, -Queue-ID, -Received, -Direction, -Source, -SHA256
and X-Archive-Signature), `envelope` (sender and recipients under
`header_from` / `header_rcpt`), `none`
type: string
enum:
- archivecow
- envelope
- none
signing_secret:
description: key of X-Archive-Signature (HMAC-SHA256), never returned
type: string
header_from:
type: string
default: X-Envelope-From
header_rcpt:
type: string
default: X-Envelope-To
action:
type: string
enum:
- test
- testmail
example:
items:
- archive
attr:
enabled: "1"
address: journal@archive.example.org
host: archive.example.org
port: 25
tls: encrypt
profile: archivecow
signing_secret: secret-key
responses:
"200":
$ref: "#/components/responses/WriteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
tags:
- name: Domains
description: >-
Domains, alias domains, domain templates, MTA-STS policies and
domain-wide footers
- name: Domain antispam policies
description: Sender allow lists (whitelists) and deny lists (blacklists) of domains
- name: Mailboxes
description: Mailboxes, their templates, tags, ACLs and logins
- name: Aliases
description: You can manage aliases
- name: Sync jobs
description: Using Syncjobs you can sync your mails with other email servers
- name: Logs
description: Logs of the mailcow containers and the UI
- name: Queue Manager
description: Manage the postfix mail queue
- name: Quarantine
description: Check what emails went to quarantine
- name: Fail2Ban
description: Manage the Netfilter fail2ban options
- name: DKIM
description: Generate, import, copy and delete DKIM keys
- name: Domain admin
description: Domain administrators, their domains and ACLs
- name: Single Sign-On
description: Login tokens for domain administrators
- name: Address Rewriting
description: BCC maps and recipient maps
- name: Outgoing TLS Policy Map Overrides
description: TLS policies for outgoing connections to single destinations
- name: oAuth Clients
description: Clients that use mailcow as OAuth2 server
- name: API Keys
description: API keys; service keys from mailcow.conf are read-only
- name: Groups
description: Mailbox groups (distribution lists, send-as rights, templates)
- name: Routing
description: Sender-dependent transports (relay hosts) and transport maps for outgoing mail
- name: Resources
description: Bookable resources (rooms, equipment, groups) for SOGo
- name: App Passwords
description: Separate passwords of a mailbox for single clients and protocols
- name: Status
description: Containers, mail storage, host and version
- name: Ratelimits
description: Edit domain ratelimits
- name: Cross-Origin Resource Sharing (CORS)
description: Origins and methods that may call the API from a browser
- name: Identity Provider
description: >-
External Identity Provider (Keycloak, OpenID Connect, LDAP): settings,
identity sync and links of mailboxes
- name: Mailbox user settings
description: >-
Settings a mailbox user changes on its own page (with the matching user
ACL): time-limited aliases, spam score, TLS policy, tagged mail,
Pushover. API keys can change them for any mailbox and must name the
mailbox; a mailbox user only for its own.
- name: Mailbox filters
description: Sieve filters of mailboxes, managed by admins and domain admins
- name: Mailbox antispam policies
description: Sender allow and deny lists of mailboxes
- name: Forwarding Hosts
description: >-
Hosts whose incoming mail is accepted unconditionally, e.g. servers that
forward mail to mailcow
- name: Rspamd
description: Rspamd settings rules, global regex maps, presets and statistics
- name: Global filters
description: Global Sieve filters that run before and after the filters of the mailboxes, Sieve presets
- name: Quota notifications
description: Mails to users whose mailbox is nearly full
- name: Administrators
description: Administrator accounts
- name: Password policy
description: Password rules and the password reset e-mail
- name: UI customization
description: Texts, links, login page and theme of the mailcow UI
- name: Mail policies
description: Whom mailboxes and groups may send to and receive from
- name: Retention rules
description: Delete mail from folders after a number of days
- name: Backup
description: Encrypted backups with restic, restore of mailboxes and domains
- name: Archive
description: >-
Archiving (SMTP journaling): a copy of every accepted incoming, outgoing and internal
mail of archived mailboxes goes by SMTP to the archive, through the Postfix queue.