Introduction of the Mailu RESTful API.

Anything that can be configured in the web administration interface,
can also be configured via the Mailu RESTful API.
See the section Advanced configuration in the configuration reference
for the relevant settings in mailu.env for enabling the API.
(API, WEB_API, API_TOKEN).
main
Dimitri Huisman 2 years ago committed by Alexander Graf
parent 866ad89dfc
commit 5c9cdfe1de
No known key found for this signature in database
GPG Key ID: B8A9DC143E075629

1
.gitignore vendored

@ -10,6 +10,7 @@ pip-selfcheck.json
/docs/include
/docs/_build
/.env
/.venv
/docker-compose.yml
/.idea
/.vscode

@ -74,8 +74,8 @@ def create_app_from_config(config):
app.register_blueprint(ui.ui, url_prefix=app.config['WEB_ADMIN'])
app.register_blueprint(internal.internal, url_prefix='/internal')
app.register_blueprint(sso.sso, url_prefix='/sso')
if app.config.get('API'):
api.register(app)
if app.config.get('API_TOKEN'):
api.register(app, web_api=app.config.get('WEB_API'))
return app

@ -1,21 +1,20 @@
from flask import redirect, url_for
# import api version(s)
from flask_restx import apidoc
from . import v1
# api
ROOT='/api'
ACTIVE=v1
# patch url for swaggerui static assets
from flask_restx.apidoc import apidoc
apidoc.static_url_path = f'{ROOT}/swaggerui'
def register(app):
def register(app, web_api):
ACTIVE=v1
ROOT=web_api
v1.app = app
# register api bluprint(s)
apidoc.apidoc.url_prefix = f'{ROOT}/v{int(v1.VERSION)}'
v1.api_token = app.config['API_TOKEN']
app.register_blueprint(v1.blueprint, url_prefix=f'{ROOT}/v{int(v1.VERSION)}')
# add redirect to current api version
@app.route(f'{ROOT}/')
def redir():
@ -25,14 +24,4 @@ def register(app):
app.config.SWAGGER_UI_DOC_EXPANSION = 'list'
app.config.SWAGGER_UI_OPERATION_ID = True
app.config.SWAGGER_UI_REQUEST_DURATION = True
# TODO: remove patch of static assets for debugging
import os
if 'STATIC_ASSETS' in os.environ:
app.blueprints['ui'].static_folder = os.environ['STATIC_ASSETS']
# TODO: authentication via username + password
# TODO: authentication via api token
# TODO: api access for all users (via token)
# TODO: use permissions from "manager_of"
# TODO: switch to marshmallow, as parser is deprecated. use flask_accepts?
app.config.RESTX_MASK_SWAGGER = False

@ -1,4 +1,9 @@
from .. import models
from .. import models, utils
from . import v1
from flask import request
import flask
from functools import wraps
from flask_restx import abort
def fqdn_in_use(*names):
for name in names:
@ -6,3 +11,19 @@ def fqdn_in_use(*names):
if model.query.get(name):
return model
return None
""" Decorator for validating api token for authentication """
def api_token_authorization(func):
@wraps(func)
def decorated_function(*args, **kwds):
client_ip = flask.request.headers.get('X-Real-IP', flask.request.remote_addr)
if utils.limiter.should_rate_limit_ip(client_ip):
abort(429, 'Too many attempts from your IP (rate-limit)' )
if request.args.get('api_token') != v1.api_token:
utils.limiter.rate_limit_ip(client_ip)
flask.current_app.logger.warn(f'Invalid API token provided by {client_ip}.')
abort(401, 'A valid API token is expected as query string parameter')
else:
flask.current_app.logger.info(f'Valid API token provided by {client_ip}.')
return func(*args, **kwds)
return decorated_function

@ -1,14 +1,28 @@
from flask import Blueprint
from flask_restx import Api, fields
VERSION = 1.0
api_token = None
blueprint = Blueprint(f'api_v{int(VERSION)}', __name__)
authorization = {
'apikey': {
'type': 'apiKey',
'in': 'query',
'name': 'api_token'
}
}
api = Api(
blueprint, version=f'{VERSION:.1f}',
title='Mailu API', default_label='Mailu',
validate=True
validate=True,
authorizations=authorization,
security='apikey',
doc='/swaggerui/'
)
response_fields = api.model('Response', {
@ -25,3 +39,6 @@ error_fields = api.model('Error', {
})
from . import domains
from . import alias
from . import relay
from . import user

@ -0,0 +1,128 @@
from flask_restx import Resource, fields, marshal
from . import api, response_fields
from .. import common
from ... import models
db = models.db
alias = api.namespace('alias', description='Alias operations')
alias_fields = api.model('Alias', {
'email': fields.String(description='the alias email address', example='user@example.com', required=True),
'comment': fields.String(description='a comment'),
'destination': fields.List(fields.String(description='alias email address', example='user@example.com', required=True)),
'wildcard': fields.Boolean(description='enable SQL Like wildcard syntax')
})
alias_fields_update = api.model('AliasUpdate', {
'comment': fields.String(description='a comment'),
'destination': fields.List(fields.String(description='alias email address', example='user@example.com')),
'wildcard': fields.Boolean(description='enable SQL Like wildcard syntax')
})
@alias.route('')
class Aliases(Resource):
@alias.doc('list_alias')
@alias.marshal_with(alias_fields, as_list=True, skip_none=True, mask=None)
@alias.doc(security='apikey')
@common.api_token_authorization
def get(self):
""" List aliases """
return models.Alias.query.all()
@alias.doc('create_alias')
@alias.expect(alias_fields)
@alias.response(200, 'Success', response_fields)
@alias.response(400, 'Input validation exception', response_fields)
@alias.response(409, 'Duplicate alias', response_fields)
@alias.doc(security='apikey')
@common.api_token_authorization
def post(self):
""" Create a new alias """
data = api.payload
alias_found = models.Alias.query.filter_by(email = data['email']).all()
if alias_found:
return { 'code': 409, 'message': f'Duplicate alias {data["email"]}'}, 409
alias_model = models.Alias(email=data["email"],destination=data['destination'])
if 'comment' in data:
alias_model.comment = data['comment']
if 'wildcard' in data:
alias_model.wildcard = data['wildcard']
db.session.add(alias_model)
db.session.commit()
return {'code': 200, 'message': f'Alias {data["email"]} to destination {data["destination"]} has been created'}, 200
@alias.route('/<string:alias>')
class Alias(Resource):
@alias.doc('find_alias')
@alias.response(200, 'Success', alias_fields)
@alias.response(404, 'Alias not found', response_fields)
@alias.doc(security='apikey')
@common.api_token_authorization
def get(self, alias):
""" Find alias """
alias_found = models.Alias.query.filter_by(email = alias).all()
if alias_found is None:
return { 'code': 404, 'message': f'Alias {alias} cannot be found'}, 404
else:
return marshal(alias_found,alias_fields), 200
@alias.doc('update_alias')
@alias.expect(alias_fields_update)
@alias.response(200, 'Success', response_fields)
@alias.response(404, 'Alias not found', response_fields)
@alias.response(400, 'Input validation exception', response_fields)
@alias.doc(security='apikey')
@common.api_token_authorization
def put(self, alias):
""" Update alias """
data = api.payload
alias_found = models.Alias.query.filter_by(email = alias).first()
if alias_found is None:
return { 'code': 404, 'message': f'Alias {alias} cannot be found'}, 404
if 'comment' in data:
alias_found.comment = data['comment']
if 'destination' in data:
destination_csl = ",".join(data['destination'])
alias_found.destination = destination_csl
if 'wildcard' in data:
alias_found.wildcard = data['wildcard']
db.session.add(alias_found)
db.session.commit()
return {'code': 200, 'message': f'Alias {alias} has been updated'}
@alias.doc('delete_alias')
@alias.response(200, 'Success', response_fields)
@alias.response(404, 'Alias not found', response_fields)
@alias.doc(security='apikey')
@common.api_token_authorization
def delete(self, alias):
""" Delete alias """
alias_found = models.Alias.query.filter_by(email = alias).first()
if alias_found is None:
return { 'code': 404, 'message': f'Alias {alias} cannot be found'}, 404
db.session.delete(alias_found)
db.session.commit()
return {'code': 200, 'message': f'Alias {alias} has been deleted'}, 200
@alias.route('/destination/<string:domain>')
class AliasWithDest(Resource):
@alias.doc('find_alias_filter_domain')
@alias.response(200, 'Success', alias_fields)
@alias.response(404, 'Alias or domain not found', response_fields)
@alias.doc(security='apikey')
@common.api_token_authorization
def get(self, domain):
""" Find aliases of domain """
domain_found = models.Domain.query.filter_by(name=domain).first()
if domain_found is None:
return { 'code': 404, 'message': f'Domain {domain} cannot be found'}, 404
aliases_found = domain_found.aliases
if aliases_found.count == 0:
return { 'code': 404, 'message': f'No alias can be found for domain {domain}'}, 404
else:
return marshal(aliases_found, alias_fields), 200

@ -1,6 +1,6 @@
from flask_restx import Resource, fields, abort
from . import api, response_fields, error_fields
import validators
from flask_restx import Resource, fields, marshal
from . import api, response_fields, user
from .. import common
from ... import models
@ -10,35 +10,76 @@ dom = api.namespace('domain', description='Domain operations')
alt = api.namespace('alternative', description='Alternative operations')
domain_fields = api.model('Domain', {
'name': fields.String(description='FQDN', example='example.com', required=True),
'name': fields.String(description='FQDN (e.g. example.com)', example='example.com', required=True),
'comment': fields.String(description='a comment'),
'max_users': fields.Integer(description='maximum number of users', min=-1, default=-1),
'max_aliases': fields.Integer(description='maximum number of aliases', min=-1, default=-1),
'max_quota_bytes': fields.Integer(description='maximum quota for mailbox', min=0),
'signup_enabled': fields.Boolean(description='allow signup'),
# 'dkim_key': fields.String,
'alternatives': fields.List(fields.String(attribute='name', description='FQDN', example='example.com')),
'alternatives': fields.List(fields.String(attribute='name', description='FQDN', example='example2.com')),
})
# TODO - name ist required on creation but immutable on change
# TODO - name and alteranatives need to be checked to be a fqdn (regex)
domain_parser = api.parser()
domain_parser.add_argument('max_users', type=int, help='maximum number of users')
# TODO ... add more (or use marshmallow)
domain_fields_update = api.model('DomainUpdate', {
'comment': fields.String(description='a comment'),
'max_users': fields.Integer(description='maximum number of users', min=-1, default=-1),
'max_aliases': fields.Integer(description='maximum number of aliases', min=-1, default=-1),
'max_quota_bytes': fields.Integer(description='maximum quota for mailbox', min=0),
'signup_enabled': fields.Boolean(description='allow signup'),
'alternatives': fields.List(fields.String(attribute='name', description='FQDN', example='example2.com')),
})
alternative_fields = api.model('Domain', {
'name': fields.String(description='alternative FQDN', example='example.com', required=True),
domain_fields_get = api.model('DomainGet', {
'name': fields.String(description='FQDN (e.g. example.com)', example='example.com', required=True),
'comment': fields.String(description='a comment'),
'max_users': fields.Integer(description='maximum number of users', min=-1, default=-1),
'max_aliases': fields.Integer(description='maximum number of aliases', min=-1, default=-1),
'max_quota_bytes': fields.Integer(description='maximum quota for mailbox', min=0),
'signup_enabled': fields.Boolean(description='allow signup'),
'alternatives': fields.List(fields.String(attribute='name', description='FQDN', example='example2.com')),
'dns_autoconfig': fields.List(fields.String(description='DNS client auto-configuration entry')),
'dns_mx': fields.String(Description='MX record for domain'),
'dns_spf': fields.String(Description='SPF record for domain'),
'dns_dkim': fields.String(Description='DKIM record for domain'),
'dns_dmarc': fields.String(Description='DMARC record for domain'),
'dns_dmarc_report': fields.String(Description='DMARC report record for domain'),
'dns_tlsa': fields.String(Description='TLSA record for domain'),
})
domain_fields_dns = api.model('DomainDNS', {
'dns_autoconfig': fields.List(fields.String(description='DNS client auto-configuration entry')),
'dns_mx': fields.String(Description='MX record for domain'),
'dns_spf': fields.String(Description='SPF record for domain'),
'dns_dkim': fields.String(Description='DKIM record for domain'),
'dns_dmarc': fields.String(Description='DMARC record for domain'),
'dns_dmarc_report': fields.String(Description='DMARC report record for domain'),
'dns_tlsa': fields.String(Description='TLSA record for domain'),
})
manager_fields = api.model('Manager', {
'domain_name': fields.String(description='domain managed by manager'),
'user_email': fields.String(description='email address of manager'),
})
manager_fields_create = api.model('ManagerCreate', {
'user_email': fields.String(description='email address of manager', required=True),
})
alternative_fields_update = api.model('AlternativeDomainUpdate', {
'domain': fields.String(description='domain FQDN', example='example.com', required=False),
})
alternative_fields = api.model('AlternativeDomain', {
'name': fields.String(description='alternative FQDN', example='example2.com', required=True),
'domain': fields.String(description='domain FQDN', example='example.com', required=True),
'dkim_key': fields.String,
})
# TODO: domain and name are not always required and can't be changed
@dom.route('')
class Domains(Resource):
@dom.doc('list_domain')
@dom.marshal_with(domain_fields, as_list=True, skip_none=True, mask=['dkim_key'])
@dom.marshal_with(domain_fields_get, as_list=True, skip_none=True, mask=None)
@dom.doc(security='apikey')
@common.api_token_authorization
def get(self):
""" List domains """
return models.Domain.query.all()
@ -46,138 +87,324 @@ class Domains(Resource):
@dom.doc('create_domain')
@dom.expect(domain_fields)
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', error_fields)
@dom.response(409, 'Duplicate domain name', error_fields)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(409, 'Duplicate domain/alternative name', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def post(self):
""" Create a new domain """
data = api.payload
if common.fqdn_in_use(data['name']):
abort(409, f'Duplicate domain name {data["name"]!r}', errors={
'name': data['name'],
})
for item, created in models.Domain.from_dict(data):
if not created:
abort(409, f'Duplicate domain name {item.name!r}', errors={
'alternatives': item.name,
})
db.session.add(item)
db.session.commit()
if not validators.domain(data['name']):
return { 'code': 400, 'message': f'Domain {data["name"]} is not a valid domain'}, 400
@dom.route('/<name>')
if common.fqdn_in_use(data['name']):
return { 'code': 409, 'message': f'Duplicate domain name {data["name"]}'}, 409
if 'alternatives' in data:
#check if duplicate alternatives are supplied
if [x for x in data['alternatives'] if data['alternatives'].count(x) >= 2]:
return { 'code': 409, 'message': f'Duplicate alternative domain names in request' }, 409
for item in data['alternatives']:
if common.fqdn_in_use(item):
return { 'code': 409, 'message': f'Duplicate alternative domain name {item}' }, 409
if not validators.domain(item):
return { 'code': 400, 'message': f'Alternative domain {item} is not a valid domain'}, 400
for item in data['alternatives']:
alternative = models.Alternative(name=item, domain_name=data['name'])
models.db.session.add(alternative)
domain_new = models.Domain(name=data['name'])
if 'comment' in data:
domain_new.comment = data['comment']
if 'max_users' in data:
domain_new.comment = data['max_users']
if 'max_aliases' in data:
domain_new.comment = data['max_aliases']
if 'max_quota_bytes' in data:
domain_new.comment = data['max_quota_bytes']
if 'signup_enabled' in data:
domain_new.comment = data['signup_enabled']
models.db.session.add(domain_new)
#apply the changes
db.session.commit()
return {'code': 200, 'message': f'Domain {data["name"]} has been created'}, 200
@dom.route('/<domain>')
class Domain(Resource):
@dom.doc('get_domain')
@dom.doc('find_domain')
@dom.response(200, 'Success', domain_fields)
@dom.response(404, 'Domain not found')
@dom.marshal_with(domain_fields)
def get(self, name):
@dom.response(404, 'Domain not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def get(self, domain):
""" Find domain by name """
domain = models.Domain.query.get(name)
if not domain:
abort(404)
return domain
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain_found = models.Domain.query.get(domain)
if not domain_found:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
return marshal(domain_found, domain_fields_get), 200
@dom.doc('update_domain')
@dom.expect(domain_fields)
@dom.expect(domain_fields_update)
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', error_fields)
@dom.response(404, 'Domain not found')
def put(self, name):
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'Domain not found', response_fields)
@dom.response(409, 'Duplicate domain/alternative name', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def put(self, domain):
""" Update an existing domain """
domain = models.Domain.query.get(name)
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain_found = models.Domain.query.get(domain)
if not domain:
abort(404)
return { 'code': 404, 'message': f'Domain {data["name"]} does not exist'}, 404
data = api.payload
data['name'] = name
for item, created in models.Domain.from_dict(data):
if created is True:
db.session.add(item)
db.session.commit()
@dom.doc('modify_domain')
@dom.expect(domain_parser)
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', error_fields)
@dom.response(404, 'Domain not found')
def post(self, name=None):
""" Updates domain with form data """
domain = models.Domain.query.get(name)
if not domain:
abort(404)
data = dict(domain_parser.parse_args())
data['name'] = name
for item, created in models.Domain.from_dict(data):
if created is True:
db.session.add(item)
# TODO: flush?
if 'alternatives' in data:
#check if duplicate alternatives are supplied
if [x for x in data['alternatives'] if data['alternatives'].count(x) >= 2]:
return { 'code': 409, 'message': f'Duplicate alternative domain names in request' }, 409
for item in data['alternatives']:
if common.fqdn_in_use(item):
return { 'code': 409, 'message': f'Duplicate alternative domain name {item}' }, 409
if not validators.domain(item):
return { 'code': 400, 'message': f'Alternative domain {item} is not a valid domain'}, 400
for item in data['alternatives']:
alternative = models.Alternative(name=item, domain_name=data['name'])
models.db.session.add(alternative)
if 'comment' in data:
domain_found.comment = data['comment']
if 'max_users' in data:
domain_found.comment = data['max_users']
if 'max_aliases' in data:
domain_found.comment = data['max_aliases']
if 'max_quota_bytes' in data:
domain_found.comment = data['max_quota_bytes']
if 'signup_enabled' in data:
domain_found.comment = data['signup_enabled']
models.db.session.add(domain_found)
#apply the changes
db.session.commit()
return {'code': 200, 'message': f'Domain {domain} has been updated'}, 200
@dom.doc('delete_domain')
@dom.response(200, 'Success', response_fields)
@dom.response(404, 'Domain not found')
def delete(self, name=None):
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'Domain not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def delete(self, domain):
""" Delete domain """
domain = models.Domain.query.get(name)
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain_found = models.Domain.query.get(domain)
if not domain:
abort(404)
db.session.delete(domain)
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
db.session.delete(domain_found)
db.session.commit()
return {'code': 200, 'message': f'Domain {domain} has been deleted'}, 200
@dom.route('/<domain>/dkim')
class Domain(Resource):
@dom.doc('generate_dkim')
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'Domain not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def post(self, domain):
""" Generate new DKIM/DMARC keys for domain """
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain_found = models.Domain.query.get(domain)
if not domain_found:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
domain_found.generate_dkim_key()
domain_found.save_dkim_key()
return {'code': 200, 'message': f'DKIM/DMARC keys have been generated for domain {domain}'}, 200
@dom.route('/<domain>/manager')
class Manager(Resource):
@dom.doc('list_managers')
@dom.marshal_with(manager_fields, as_list=True, skip_none=True, mask=None)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'domain not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def get(self, domain):
""" List managers of domain """
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
if not domain:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
domain = models.Domain.query.filter_by(name=domain)
return domain.managers
@dom.doc('create_manager')
@dom.expect(manager_fields_create)
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'User or domain not found', response_fields)
@dom.response(409, 'Duplicate domain manager', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def post(self, domain):
""" Create a new domain manager """
data = api.payload
if not validators.email(data['user_email']):
return {'code': 400, 'message': f'Invalid email address {data["user_email"]}'}, 400
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain = models.Domain.query.get(domain)
if not domain:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
user = models.User.query.get(data['user_email'])
if not user:
return { 'code': 404, 'message': f'User {data["user_email"]} does not exist'}, 404
if user in domain.managers:
return {'code': 409, 'message': f'User {data["user_email"]} is already a manager of the domain {domain} '}, 409
domain.managers.append(user)
models.db.session.commit()
return {'code': 200, 'message': f'User {data["user_email"]} has been added as manager of the domain {domain} '},200
@dom.route('/<domain>/manager/<email>')
class Domain(Resource):
@dom.doc('find_manager')
@dom.response(200, 'Success', manager_fields)
@dom.response(404, 'Manager not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def get(self, domain, email):
""" Find manager by email address """
if not validators.email(email):
return {'code': 400, 'message': f'Invalid email address {email}'}, 400
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain = models.Domain.query.get(domain)
if not domain:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
user = models.User.query.get(email)
if not user:
return { 'code': 404, 'message': f'User {email} does not exist'}, 404
if user in domain.managers:
for manager in domain.managers:
if manager.email == email:
return marshal(manager, manager_fields),200
else:
return { 'code': 404, 'message': f'User {email} is not a manager of the domain {domain}'}, 404
# @dom.route('/<name>/alternative')
# @alt.route('')
# class Alternatives(Resource):
@dom.doc('delete_manager')
@dom.response(200, 'Success', response_fields)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'Manager not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def delete(self, domain, email):
if not validators.email(email):
return {'code': 400, 'message': f'Invalid email address {email}'}, 400
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain = models.Domain.query.get(domain)
if not domain:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
user = models.User.query.get(email)
if not user:
return { 'code': 404, 'message': f'User {email} does not exist'}, 404
if user in domain.managers:
domain.managers.remove(user)
models.db.session.commit()
return {'code': 200, 'message': f'User {email} has been removed as a manager of the domain {domain} '},200
else:
return { 'code': 404, 'message': f'User {email} is not a manager of the domain {domain}'}, 404
# @alt.doc('alternatives_list')
# @alt.marshal_with(alternative_fields, as_list=True, skip_none=True, mask=['dkim_key'])
# def get(self, name=None):
# """ List alternatives (of domain) """
# if name is None:
# return models.Alternative.query.all()
# else:
# return models.Alternative.query.filter_by(domain_name = name).all()
@dom.route('/<domain>/users')
class User(Resource):
@dom.doc('list_user_domain')
@dom.marshal_with(user.user_fields_get, as_list=True, skip_none=True, mask=None)
@dom.response(400, 'Input validation exception', response_fields)
@dom.response(404, 'Domain not found', response_fields)
@dom.doc(security='apikey')
@common.api_token_authorization
def get(self, domain):
""" List users from domain """
if not validators.domain(domain):
return { 'code': 400, 'message': f'Domain {domain} is not a valid domain'}, 400
domain_found = models.Domain.query.get(domain)
if not domain_found:
return { 'code': 404, 'message': f'Domain {domain} does not exist'}, 404
return models.User.query.filter_by(domain=domain_found).all()
# @alt.doc('alternative_create')
# @alt.expect(alternative_fields)
# @alt.response(200, 'Success', response_fields)
# @alt.response(400, 'Input validation exception', error_fields)
# @alt.response(404, 'Domain not found')
# @alt.response(409, 'Duplicate domain name', error_fields)
# def post(self, name=None):
# """ Create new alternative (for domain) """
# # abort(501)
# data = api.payload
# if name is not None:
# data['name'] = name
# domain = models.Domain.query.get(name)
# if not domain:
# abort(404)
# if common.fqdn_in_use(data['name']):
# abort(409, f'Duplicate domain name {data["name"]!r}', errors={
# 'name': data['name'],
# })
# for item, created in models.Alternative.from_dict(data):
# # TODO: handle creation of domain
# if not created:
# abort(409, f'Duplicate domain name {item.name!r}', errors={
# 'alternatives': item.name,
# })
# # db.session.add(item)
# # db.session.commit()
@alt.route('')
class Alternatives(Resource):
# @dom.route('/<name>/alternative/<alt>')
# @alt.route('/<name>')
# class Alternative(Resource):
# def get(self, name, alt=None):
# """ Find alternative (of domain) """
# abort(501)
# def put(self, name, alt=None):
# """ Update alternative (of domain) """
# abort(501)
# def post(self, name, alt=None):
# """ Update alternative (of domain) with form data """
# abort(501)
# def delete(self, name, alt=None):
# """ Delete alternative (for domain) """
# abort(501)
@alt.doc('list_alternative')
@alt.marshal_with(alternative_fields, as_list=True, skip_none=True, mask=None)
@alt.doc(security='apikey')
@common.api_token_authorization
def get(self):
""" List alternatives """
return models.Alternative.query.all()
@alt.doc('create_alternative')
@alt.expect(alternative_fields)
@alt.response(200, 'Success', response_fields)
@alt.response(400, 'Input validation exception', response_fields)
@alt.response(404, 'Domain not found or missing', response_fields)
@alt.response(409, 'Duplicate alternative domain name', response_fields)
@alt.doc(security='apikey')
@common.api_token_authorization
def post(self):
""" Create new alternative (for domain) """
data = api.payload
if not validators.domain(data['name']):
return { 'code': 400, 'message': f'Alternative domain {data["name"]} is not a valid domain'}, 400
if not validators.domain(data['domain']):
return { 'code': 400, 'message': f'Domain {data["domain"]} is not a valid domain'}, 400
domain = models.Domain.query.get(data['domain'])
if not domain:
return { 'code': 404, 'message': f'Domain {data["domain"]} does not exist'}, 404
if common.fqdn_in_use(data['name']):
return { 'code': 409, 'message': f'Duplicate alternative domain name {data["name"]}'}, 409
alternative = models.Alternative(name=data['name'], domain_name=data['domain'])
models.db.session.add(alternative)
db.session.commit()
return {'code': 200, 'message': f'Alternative {data["name"]} for domain {data["domain"]} has been created'}, 200
@alt.route('/<string:alt>')
class Alternative(Resource):
@alt.doc('find_alternative')
@alt.doc(security='apikey')
@common.api_token_authorization
def get(self, alt):
""" Find alternative (of domain) """
if not validators.domain(alt):
return { 'code': 400, 'message': f'Alternative domain {alt} is not a valid domain'}, 400
alternative = models.Alternative.query.filter_by(name=alt).first()
if not alternative:
return{ 'code': 404, 'message': f'Alternative domain {alt} does not exist'}, 404
return marshal(alternative, alternative_fields), 200
@alt.doc('delete_alternative')
@alt.response(200, 'Success', response_fields)
@alt.response(400, 'Input validation exception', response_fields)
@alt.response(404, 'Alternative/Domain not found or missing', response_fields)
@alt.response(409, 'Duplicate domain name', response_fields)
@alt.doc(security='apikey')
@common.api_token_authorization
def delete(self, alt):
""" Delete alternative (for domain) """
if not validators.domain(alt):
return { 'code': 400, 'message': f'Alternative domain {alt} is not a valid domain'}, 400
alternative = models.Alternative.query.filter_by(name=alt).first
if not alternative:
return { 'code': 404, 'message': f'Alternative domain {alt} does not exist'}, 404
domain = alternative.domain
db.session.delete(alternative)
db.session.commit()
return {'code': 200, 'message': f'Alternative {alt} for domain {domain} has been deleted'}, 200

@ -0,0 +1,119 @@
from flask_restx import Resource, fields, marshal
import validators
from . import api, response_fields
from .. import common
from ... import models
db = models.db
relay = api.namespace('relay', description='Relay operations')
relay_fields = api.model('Relay', {
'name': fields.String(description='relayed domain name', example='example.com', required=True),
'smtp': fields.String(description='remote host', example='example.com', required=False),
'comment': fields.String(description='a comment', required=False)
})
relay_fields_update = api.model('RelayUpdate', {
'smtp': fields.String(description='remote host', example='example.com', required=False),
'comment': fields.String(description='a comment', required=False)
})
@relay.route('')
class Relays(Resource):
@relay.doc('list_relays')
@relay.marshal_with(relay_fields, as_list=True, skip_none=True, mask=None)
@relay.doc(security='apikey')
@common.api_token_authorization
def get(self):
"List relays"
return models.Relay.query.all()
@relay.doc('create_relay')
@relay.expect(relay_fields)
@relay.response(200, 'Success', response_fields)
@relay.response(400, 'Input validation exception')
@relay.response(409, 'Duplicate relay', response_fields)
@relay.doc(security='apikey')
@common.api_token_authorization
def post(self):
""" Create relay """
data = api.payload
if not validators.domain(name):
return { 'code': 400, 'message': f'Relayed domain {name} is not a valid domain'}, 400
relay_found = models.Relay.query.filter_by(name=data['name']).all()
if common.fqdn_in_use(data['name']):
return { 'code': 409, 'message': f'Duplicate domain {data["name"]}'}, 409
relay_model = models.Relay(name=data['name'])
if 'smtp' in data:
relay_model.smtp = data['smtp']
if 'comment' in data:
relay_model.comment = data['comment']
db.session.add(relay_model)
db.session.commit()
return {'code': 200, 'message': f'Relayed domain {data["name"]} has been created'}, 200
@relay.route('/<string:name>')
class Relay(Resource):
@relay.doc('find_relay')
@relay.response(400, 'Input validation exception', response_fields)
@relay.response(404, 'Relay not found', response_fields)
@relay.doc(security='apikey')
@common.api_token_authorization
def get(self, name):
""" Find relay """
if not validators.domain(name):
return { 'code': 400, 'message': f'Relayed domain {name} is not a valid domain'}, 400
relay_found = models.Relay.query.filter_by(name=name).first()
if relay_found is None:
return { 'code': 404, 'message': f'Relayed domain {name} cannot be found'}, 404
return marshal(relay_found, relay_fields), 200
@relay.doc('update_relay')
@relay.expect(relay_fields_update)
@relay.response(200, 'Success', response_fields)
@relay.response(400, 'Input validation exception', response_fields)
@relay.response(404, 'Relay not found', response_fields)
@relay.response(409, 'Duplicate relay', response_fields)
@relay.doc(security='apikey')
@common.api_token_authorization
def put(self, name):
""" Update relay """
data = api.payload
if not validators.domain(name):
return { 'code': 400, 'message': f'Relayed domain {name} is not a valid domain'}, 400
relay_found = models.Relay.query.filter_by(name=name).first()
if relay_found is None:
return { 'code': 404, 'message': f'Relayed domain {name} cannot be found'}, 404
if 'smtp' in data:
relay_found.smtp = data['smtp']
if 'comment' in data:
relay_found.comment = data['comment']
db.session.add(relay_found)
db.session.commit()
return { 'code': 200, 'message': f'Relayed domain {name} has been updated'}, 200
@relay.doc('delete_relay')
@relay.response(200, 'Success', response_fields)
@relay.response(400, 'Input validation exception', response_fields)
@relay.response(404, 'Relay not found', response_fields)
@relay.doc(security='apikey')
@common.api_token_authorization
def delete(self, name):
""" Delete relay """
if not validators.domain(name):
return { 'code': 400, 'message': f'Relayed domain {name} is not a valid domain'}, 400
relay_found = models.Relay.query.filter_by(name=name).first()
if relay_found is None:
return { 'code': 404, 'message': f'Relayed domain {name} cannot be found'}, 404
db.session.delete(relay_found)
db.session.commit()
return { 'code': 200, 'message': f'Relayed domain {name} has been deleted'}, 200

@ -0,0 +1,255 @@
from flask_restx import Resource, fields, marshal
import validators, datetime
from . import api, response_fields
from .. import common
from ... import models
db = models.db
user = api.namespace('user', description='User operations')
user_fields_get = api.model('UserGet', {
'email': fields.String(description='The email address of the user', example='John.Doe@example.com', attribute='_email'),
'password': fields.String(description='PBKDF2-HMAC-SHA256 based password of the user. For more info see passlib.hash.pbkdf2_sha256', example='$pbkdf2-sha256$1$.6UI/S.nXIk8jcbdHx3Fhg$98jZicV16ODfEsEZeYPGHU3kbrUrvUEXOPimVSQDD44'),
'comment': fields.String(description='A description for the user. This description is shown on the Users page', example='my comment'),
'quota_bytes': fields.Integer(description='The maximum quota for the users email box in bytes', example='1000000000'),
'global_admin': fields.Boolean(description='Make the user a global administrator'),
'enabled': fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap': fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop': fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled': fields.Boolean(description='Enable auto forwarding'),
'forward_destination': fields.List(fields.String(description='Email address to forward emails to'), example='Other@example.com'),
'forward_keep': fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled': fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject': fields.String(description='Optional subject for the automatic reply', example='Out of office'),
'reply_body': fields.String(description='The body of the automatic reply email', example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate': fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.', example='2022-02-10'),
'reply_enddate': fields.Date(description='End date for automatic replies in YYYY-MM-DD format.', example='2022-02-22'),
'displayed_name': fields.String(description='The display name of the user within the Admin GUI', example='John Doe'),
'spam_enabled': fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read': fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold': fields.Integer(description='The user defined spam filter tolerance', example='80'),
})
user_fields_post = api.model('UserCreate', {
'email': fields.String(description='The email address of the user', example='John.Doe@example.com', attribute='_email', required=True),
'raw_password': fields.String(description='The raw (plain text) password of the user. Mailu will hash the password using PBKDF2-HMAC-SHA256', example='secret', required=True),
'comment': fields.String(description='A description for the user. This description is shown on the Users page', example='my comment'),
'quota_bytes': fields.Integer(description='The maximum quota for the users email box in bytes', example='1000000000'),
'global_admin': fields.Boolean(description='Make the user a global administrator'),
'enabled': fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap': fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop': fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled': fields.Boolean(description='Enable auto forwarding'),
'forward_destination': fields.List(fields.String(description='Email address to forward emails to'), example='Other@example.com'),
'forward_keep': fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled': fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject': fields.String(description='Optional subject for the automatic reply', example='Out of office'),
'reply_body': fields.String(description='The body of the automatic reply email', example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate': fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.', example='2022-02-10'),
'reply_enddate': fields.Date(description='End date for automatic replies in YYYY-MM-DD format.', example='2022-02-22'),
'displayed_name': fields.String(description='The display name of the user within the Admin GUI', example='John Doe'),
'spam_enabled': fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read': fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold': fields.Integer(description='The user defined spam filter tolerance', example='80'),
})
user_fields_put = api.model('UserUpdate', {
'raw_password': fields.String(description='The raw (plain text) password of the user. Mailu will hash the password using PBKDF2-HMAC-SHA256', example='secret'),
'comment': fields.String(description='A description for the user. This description is shown on the Users page', example='my comment'),
'quota_bytes': fields.Integer(description='The maximum quota for the users email box in bytes', example='1000000000'),
'global_admin': fields.Boolean(description='Make the user a global administrator'),
'enabled': fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap': fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop': fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled': fields.Boolean(description='Enable auto forwarding'),
'forward_destination': fields.List(fields.String(description='Email address to forward emails to'), example='Other@example.com'),
'forward_keep': fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled': fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject': fields.String(description='Optional subject for the automatic reply', example='Out of office'),
'reply_body': fields.String(description='The body of the automatic reply email', example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate': fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.', example='2022-02-10'),
'reply_enddate': fields.Date(description='End date for automatic replies in YYYY-MM-DD format.', example='2022-02-22'),
'displayed_name': fields.String(description='The display name of the user within the Admin GUI', example='John Doe'),
'spam_enabled': fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read': fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold': fields.Integer(description='The user defined spam filter tolerance', example='80'),
})
@user.route('')
class Users(Resource):
@user.doc('list_users')
@user.marshal_with(user_fields_get, as_list=True, skip_none=True, mask=None)
@user.doc(security='apikey')
@common.api_token_authorization
def get(self):
"List users"
return models.User.query.all()
@user.doc('create_user')
@user.expect(user_fields_post)
@user.response(200, 'Success', response_fields)
@user.response(400, 'Input validation exception')
@user.response(409, 'Duplicate user', response_fields)
@user.doc(security='apikey')
@common.api_token_authorization
def post(self):
""" Create user """
data = api.payload
if not validators.email(data['email']):
return { 'code': 400, 'message': f'Provided email address {data["email"]} is not a valid email address'}, 400
localpart, domain_name = data['email'].lower().rsplit('@', 1)
domain_found = models.Domain.query.get(domain_name)
if not domain_found:
return { 'code': 404, 'message': f'Domain {domain_name} does not exist'}, 404
user_new = models.User(email=data['email'])
if 'raw_password' in data:
user_new.set_password(data['raw_password'])
if 'comment' in data:
user_new.comment = data['comment']
if 'quota_bytes' in data:
user_new.quota_bytes = data['quota_bytes']
if 'global_admin' in data:
user_new.global_admin = data['global_admin']
if 'enabled' in data:
user_new.enabled = data['enabled']
if 'enable_imap' in data:
user_new.enable_imap = data['enable_imap']
if 'enable_pop' in data:
user_new.enable_pop = data['enable_pop']
if 'forward_enabled' in data:
user_new.forward_enabled = data['forward_enabled']
if 'forward_destination' in data:
user_new.forward_destination = data['forward_destination']
if 'forward_keep' in data:
user_new.forward_keep = data['forward_keep']
if 'reply_enabled' in data:
user_new.reply_enabled = data['reply_enabled']
if 'reply_subject' in data:
user_new.reply_subject = data['reply_subject']
if 'reply_body' in data:
user_new.reply_body = data['reply_body']
if 'reply_startdate' in data:
year, month, day = data['reply_startdate'].split('-')
date = datetime.datetime(int(year), int(month), int(day))
user_new.reply_startdate = date
if 'reply_enddate' in data:
year, month, day = data['reply_enddate'].split('-')
date = datetime.datetime(int(year), int(month), int(day))
user_new.reply_enddate = date
if 'displayed_name' in data:
user_new.displayed_name = data['displayed_name']
if 'spam_enabled' in data:
user_new.spam_enabled = data['spam_enabled']
if 'spam_mark_as_read' in data:
user_new.spam_mark_as_read = data['spam_mark_as_read']
if 'spam_threshold' in data:
user_new.spam_threshold = data['spam_threshold']
db.session.add(user_new)
db.session.commit()
return {'code': 200,'message': f'User {data["email"]} has been created'}, 200
@user.route('/<string:email>')
class User(Resource):
@user.doc('find_user')
@user.response(400, 'Input validation exception', response_fields)
@user.response(404, 'User not found', response_fields)
@user.doc(security='apikey')
@common.api_token_authorization
def get(self, email):
""" Find user """
if not validators.email(email):
return { 'code': 400, 'message': f'Provided email address {email} is not a valid email address'}, 400
email_found = models.User.query.filter_by(email=email).first()
if email_found is None:
return { 'code': 404, 'message': f'User {email} cannot be found'}, 404
return marshal(email_found, user_fields_get), 200
@user.doc('update_user')
@user.expect(user_fields_put)
@user.response(200, 'Success', response_fields)
@user.response(400, 'Input validation exception', response_fields)
@user.response(404, 'User not found', response_fields)
@user.response(409, 'Duplicate user', response_fields)
@user.doc(security='apikey')
@common.api_token_authorization
def put(self, email):
""" Update user """
data = api.payload
if not validators.email(email):
return { 'code': 400, 'message': f'Provided email address {data["email"]} is not a valid email address'}, 400
user_found = models.User.query.filter_by(email=email).first()
if not user_found:
return {'code': 404, 'message': f'User {email} cannot be found'}, 404
if 'raw_password' in data:
user_found.set_password(data['raw_password'])
if 'comment' in data:
user_found.comment = data['comment']
if 'quota_bytes' in data:
user_found.quota_bytes = data['quota_bytes']
if 'global_admin' in data:
user_found.global_admin = data['global_admin']
if 'enabled' in data:
user_found.enabled = data['enabled']
if 'enable_imap' in data:
user_found.enable_imap = data['enable_imap']
if 'enable_pop' in data:
user_found.enable_pop = data['enable_pop']
if 'forward_enabled' in data:
user_found.forward_enabled = data['forward_enabled']
if 'forward_destination' in data:
user_found.forward_destination = data['forward_destination']
if 'forward_keep' in data:
user_found.forward_keep = data['forward_keep']
if 'reply_enabled' in data:
user_found.reply_enabled = data['reply_enabled']
if 'reply_subject' in data:
user_found.reply_subject = data['reply_subject']
if 'reply_body' in data:
user_found.reply_body = data['reply_body']
if 'reply_startdate' in data:
year, month, day = data['reply_startdate'].split('-')
date = datetime.datetime(int(year), int(month), int(day))
user_found.reply_startdate = date
if 'reply_enddate' in data:
year, month, day = data['reply_enddate'].split('-')
date = datetime.datetime(int(year), int(month), int(day))
user_found.reply_enddate = date
if 'displayed_name' in data:
user_found.displayed_name = data['displayed_name']
if 'spam_enabled' in data:
user_found.spam_enabled = data['spam_enabled']
if 'spam_mark_as_read' in data:
user_found.spam_mark_as_read = data['spam_mark_as_read']
if 'spam_threshold' in data:
user_found.spam_threshold = data['spam_threshold']
db.session.add(user_found)
db.session.commit()
return {'code': 200,'message': f'User {email} has been updated'}, 200
@user.doc('delete_user')
@user.response(200, 'Success', response_fields)
@user.response(400, 'Input validation exception', response_fields)
@user.response(404, 'User not found', response_fields)
@user.doc(security='apikey')
@common.api_token_authorization
def delete(self, email):
""" Delete user """
if not validators.email(email):
return { 'code': 400, 'message': f'Provided email address {email} is not a valid email address'}, 400
email_found = models.User.query.filter_by(email=email).first()
if email_found is None:
return { 'code': 404, 'message': f'User {email} cannot be found'}, 404
db.session.delete(email_found)
db.session.commit()
return { 'code': 200, 'message': f'User {email} has been deleted'}, 200

@ -71,6 +71,9 @@ DEFAULT_CONFIG = {
'LOGO_BACKGROUND': None,
'API': False,
# Advanced settings
'API' : 'false',
'WEB_API' : '/api',
'API_TOKEN': None,
'LOG_LEVEL': 'WARNING',
'SESSION_KEY_BITS': 128,
'SESSION_TIMEOUT': 3600,

@ -244,6 +244,13 @@ http {
{% endif %}
{% endif %}
{% if API == 'true' %}
location ~ {{ WEB_API }} {
include /etc/nginx/proxy.conf;
proxy_pass http://$admin;
}
{% endif %}
location /internal {
internal;

@ -0,0 +1,29 @@
Mailu RESTful API
=================
Mailu offers a RESTful API for changing the Mailu configuration.
Anything that can be configured via the Mailu web administration interface,
can also be configured via the API.
The Mailu API is disabled by default. It can be enabled and configured via
the settings:
* `API`
* `WEB_API`
* `API_TOKEN`
For more information see the section :ref:`Advanced configuration <advanced_settings>`
in the configuration reference.
Swagger.json
------------
The swagger.json file can be retrieved via: https://myserver/api/v1/swagger.json.
The swagger.json file can be consumed in programs such as Postman for generating all API calls.
In-built SwaggerUI
------------------
The Mailu API comes with an in-built SwaggerUI. It is a web client that allows
anyone to visualize and interact with the Mailu API.

@ -1,7 +1,7 @@
Mailu command line
==================
Managing users and aliases can be done from CLI using commands:
Managing domains, users and aliases can be done from CLI using the commands:
* alias
* alias-delete

@ -157,7 +157,7 @@ in the admin interface, while ``SITENAME`` is a customization option for
every Web interface.
- ``LOGO_BACKGROUND`` sets a custom background colour for the brand logo
in the top left of the main admin interface.
in the topleft of the main admin interface.
For a list of colour codes refer to this page of `w3schools`_.
- ``LOGO_URL`` sets a URL for a custom logo. This logo replaces the Mailu
@ -198,11 +198,20 @@ An example:
Depending on your particular deployment you most probably will want to change the default.
.. _advanced_cfg:
.. _advanced_settings:
Advanced settings
-----------------
The ``API`` (default: False) setting controls if the API endpoint is publicly
reachable.
The ``WEB_API`` (default: /api) setting configures the endpoint that the API
listens on publicly&interally. The path must always start with a leading slash.
The ``API_TOKEN`` (default: None) enables the API endpoint. This token must be
passed as query parameter with requests to the API as authentication token.
The ``CREDENTIAL_ROUNDS`` (default: 12) setting is the number of rounds used by the
password hashing scheme. The number of rounds can be reduced in case faster
authentication is needed or increased when additional protection is desired.

@ -591,7 +591,7 @@ follow these steps:
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to you needs.
The above will block flagged IPs for a week, you can of course change it to your needs.
4. In the mailu docker-compose set the logging driver of the Admin container to journald; and set the tag to mailu-admin
@ -625,9 +625,34 @@ The above will block flagged IPs for a week, you can of course change it to you
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to you needs.
The above will block flagged IPs for a week, you can of course change it to your needs.
7. Add the /etc/fail2ban/action.d/docker-action.conf
7. Add the /etc/fail2ban/filter.d/bad-auth-api.conf
.. code-block:: bash
# Fail2Ban configuration file
[Definition]
failregex = .* Invalid API token provided by <HOST>.
ignoreregex =
journalmatch = CONTAINER_TAG=mailu-admin
8. Add the /etc/fail2ban/jail.d/bad-auth-api.conf
.. code-block:: bash
[bad-auth-api]
enabled = true
backend = systemd
filter = bad-auth-api
bantime = 604800
findtime = 300
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to your needs.
9. Add the /etc/fail2ban/action.d/docker-action.conf
Option 1: Use plain iptables
@ -678,7 +703,7 @@ Using iptables with ipset might reduce the system load in such attacks significa
Using DOCKER-USER chain ensures that the blocked IPs are processed in the correct order with Docker. See more in: https://docs.docker.com/network/iptables/
1. Configure and restart the Fail2Ban service
10. Configure and restart the Fail2Ban service
Make sure Fail2Ban is started after the Docker service by adding a partial override which appends this to the existing configuration.

@ -70,6 +70,7 @@ the version of Mailu that you are running.
webadministration
antispam
cli
api
.. toctree::
:maxdepth: 2

@ -1,5 +1,5 @@
recommonmark
Sphinx
sphinx-autobuild
sphinx-rtd-theme
recommonmark==0.7.1
Sphinx==5.2.0
sphinx-autobuild==2021.3.14
sphinx-rtd-theme==1.0.0
docutils==0.16

@ -0,0 +1,2 @@
Introduction of the Mailu RESTful API. The full Mailu config can be changed via the Mailu API.
See the section Mailu RESTful API & the section configuration reference in the documentation for more information.
Loading…
Cancel
Save