What happens during shutdown of the container? Is it guaranteed that the mailq is flushed before? Are there scenarios where e-mails can be lost by shutting down/restarting the container?
There is no guarantee and there are probably scenarios where messages can be lost. Mail is not transactional like a database. However, I think that the messages are saved before they are acknowledged as accepted for delivery and not marked as delivered until acknowledged by the other side, so a "lost" message should normally be attempted again.
The docker-mailserver semantics on shutdown should not differ all that much from a normal physical server with Postfix and Dovecot where the physical server is rebooted, so you can read the documentation for that.
fyi: The default timeout of docker-compose down is 10 seconds, until SIGKILL is used to kill all running processes. In my environment I noticed, that to cleanly shutdown all services, it takes longer than 10 seconds.
docker compose down -t 60 can be used, to give the services enough time for a graceful shutdown.
Probably, it would be better to define the stop grace period inside the docker-compose.yml configuration?
https://docs.docker.com/compose/compose-file/compose-file-v2/#stop_grace_period
I agree. I didn't know about that feature until now.