Events

List of all events emitted by Dovecot.

These events can be used in Statistics and Event Export.

See Events Design for technical implementation details.

Categories

Category Description
auth  
mailbox  
storage  
sieve  
sieve-execute Relates to (several) Sieve scripts being executed for a particular message. This envelops all of Sieve execution; both runtime and action execution.
sieve-runtime Relates to the evaluation of individual scripts.
sieve-action Relates to individual actions executed.
sieve-storage Sieve storage events
managesieve Managesieve action events
smtp-server SMTP/LMTP server events
smtp-submit SMTP submission client events
service:<name> Event was sent by the named service, e.g. service:imap

Global Fields

ALL events have the following fields:

Field Description
duration Duration of the event (in microseconds)

Dovecot Core

Authentication Server

These events are generated in authentication process(es) and can be used to track and log individual authentication actions.

auth_request_finished

New in version v2.3.7.

Emitted at end of authentication request. Most useful for tracking status of authentication/login attempts.

Field Description
user Full username
original_username Original username used
translated_username Username after auth_username_translation translations are applied
login_user When doing login using master_user, the user we are logging in as
master_user Master username
error Set when error happens
success yes, when authentication succeeded
transport
Values:
  • insecure
  • trusted
  • TLS
mechanism Name of used mechanism
credentials_scheme Type of credential. Examples: SHA256-CRYPT, PLAIN, …
policy_penalty Time of penalty added by policy server
policy_result
Values:
  • ok
  • delayed
  • refused

auth_passdb_request_started

New in version v2.3.7.

Emitted before processing begins for a passdb block.

Most useful for debugging authentication flow.

Field Description
passdb Driver name
passdb_name passdb { name }, if it is configured. Otherwise, the driver name.
passdb_id

ID number of the passdb username

New in version v2.3.9.

auth_passdb_request_finished

New in version v2.3.7.

Emitted after processing ends for a passdb block.

Most useful for debugging authentication flow.

Field Description
passdb Driver name
passdb_name passdb { name }, if it is configured. Otherwise, the driver name.
user Full username
master_user Master username
username Username without domain
domain Domain (if present)
result
Values:
  • ok
  • password_mismatch
  • user_unknown
  • pass_expired
  • user_disabled
  • scheme_not_available
  • internal_failure
  • next
passdb_id

ID number of the passdb username

New in version v2.3.9.

auth_userdb_request_started

New in version v2.3.7.

Emitted before processing begins for a userdb block.

Most useful for debugging authentication flow.

Field Description
userdb Driver name
userdb_name userdb { name }, if it is configured. Otherwise, the driver name.
userdb_id

ID number of the userdb username

New in version v2.3.9.

auth_userdb_request_finished

New in version v2.3.7.

Emitted after processing ends for a userdb block.

Most useful for debugging authentication flow.

Field Description
userdb Driver name
userdb_name userdb { name }, if it is configured. Otherwise, the driver name.
user Full username
master_user Master username
username Username without domain
domain Domain (if present)
result
Values:
  • ok
  • user_unknown
  • internal_failure
userdb_id

ID number of the userdb username

New in version v2.3.9.

auth_policy_request_finished

New in version v2.3.7.

Emitted after processing ends for an auth policy request.

Most useful for debugging authentication flow.

Field Description
mode
Values:
  • allow
  • report
policy_response Value returned from policy server (number) Otherwise, the driver name.

Authentication Client

These events are generated by authentication clients (lib-auth).

auth_client_request_started

New in version v2.3.7.

Field Description
id Event ID

auth_client_request_continue

New in version v2.3.7.

Field Description
id Event ID

auth_client_request_finished

New in version v2.3.7.

Field Description
id Event ID
error Error reason

auth_client_request_challenged

New in version v2.3.7.

Field Description
id Event ID

auth_client_userdb_lookup_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username

auth_client_userdb_lookup_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred

auth_client_passdb_lookup_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username

auth_client_passdb_lookup_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred

auth_client_userdb_list_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username

auth_client_userdb_list_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred

auth_client_cache_flush_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username

auth_client_cache_flush_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred

Authentication Master Client

These events are generated by master authentication clients (lib-master). This happens when e.g. IMAP finishes the login by doing a userdb lookup.

Common fields:

Field Description
id Login request ID
local_ip Client connection’s local (server) IP
local_port Client connection’s local (server) port
remote_ip Client connection’s remote (client) IP
remote_port Client onnection’s remote (client) port

auth_master_client_login_started

Authentication master login request started.

auth_master_client_login_finished

Authentication master login request finished.

Field Description
user Username of the user
error Error message if the request failed

Connection

These events apply only for connections using the connection API.

Note

Not all connections currently use this API, so these events work for some types of connections, but not for others.

client_connection_connected

Emitted when a client connection is established.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port

client_connection_disconnected

Emitted when a client connection is terminated.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
reason Disconnection reason

server_connection_connected

Emitted when a server connection is established.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

server_connection_disconnected

Emitted when a server connection is terminated.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
reason Disconnection reason

Storage

Mail storage service user

Field Description
Inherits from environment (e.g. IMAP/LMTP client)
session Session ID for the storage sesssion

Mail user

Field Description
Inherits from mail storage service user
user Username of the user

Mailbox

Field Description
Inherits from mail user
mailbox

Full mailbox name in UTF-8

New in version v2.3.9.

Mail

Field Description
Inherits from mailbox
seq Mail sequence number
uid Mail IMAP UID number

HTTP

These events are emitted by Dovecot’s internal HTTP library.

http_request_finished

Emitted when an HTTP request is complete.

This event is useful to track and monitor external services.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

http_request_redirected

Intermediate event emitted when an HTTP request is being redirected.

The http_request_finished event is still sent at the end of the request.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

http_request_retried

Intermediate event emitted when an HTTP request is being retried.

The http_request_finished event is still sent at the end of the request.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

IMAP

IMAP client

Field Description
user Username of the user
session Session ID of the IMAP connection
local_ip

IMAP connection’s local (server) IP

New in version v2.3.9.

local_port

IMAP connection’s local (server) port

New in version v2.3.9.

remote_ip

IMAP connection’s remote (client) IP

New in version v2.3.9.

remote_port

IMAP connection’s remote (client) port

New in version v2.3.9.

IMAP command

Field Description
Inherits from IMAP client
cmd_tag

IMAP command tag

New in version v2.3.9.

cmd_name

IMAP command name (e.g. FETCH)

New in version v2.3.9.

cmd_args

IMAP command’s full parameters (e.g. 1:* FLAGS)

New in version v2.3.9.

cmd_human_args

IMAP command’s full parameters, as human-readable output. Often it’s the same as cmd_args, but it is guaranteed to contain only valid UTF-8 characters and no control characters. Multi-line parameters are written only as <N byte multi-line literal>

New in version v2.3.9.

imap_command_finished

Event emitted when an IMAP command is completed.

This event is useful to track individual command usage, debug specific sessions, and/or detect broken clients.

Note

This event is currently not sent for pre-login IMAP commands.

Field Description
tagged_reply_state
Values:
  • OK
  • NO
  • BAD
tagged_reply Full tagged reply (e.g. OK SELECT finished.)
last_run_time Timestamp when the command was running last time. (Command may be followed by internal “mailbox sync” that can take some time to complete)
running_usecs How many usecs this command has spent running
lock_wait_usecs How many usecs this command has spent waiting for locks
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

Mail Delivery

Events emitted on mail delivery.

mail_delivery_started

New in version 2.3.8.

Event emitted when message delivery is started.

This event is useful for debugging mail delivery flow.

Field Description
message_id Message-ID header value (truncated to 200 bytes)
message_subject Subject header value, in UTF-8 (truncated to 80 bytes)
message_from Email address in the From header (e.g. user@example.com)
message_size Size of the message, in bytes
message_vsize Size of the message with CRLF linefeeds, in bytes
rcpt_to The envelope recipient for the message
rcpt_param_notify The value of the NOTIFY parameter from the LMTP RCPT command
rcpt_param_orcpt The value of the ORCPT parameter from the LMTP RCPT command
rcpt_param_orcpt_type The address type, typically rfc822, of the ORCPT parameter for the LMTP RCPT command

mail_delivery_finished

New in version 2.3.8.

Event emitted when message delivery is completed.

This event is useful for logging and tracking mail deliveries.

Field Description
message_id Message-ID header value (truncated to 200 bytes)
message_subject Subject header value, in UTF-8 (truncated to 80 bytes)
message_from Email address in the From header (e.g. user@example.com)
message_size Size of the message, in bytes
message_vsize Size of the message with CRLF linefeeds, in bytes
rcpt_to The envelope recipient for the message
rcpt_param_notify The value of the NOTIFY parameter from the LMTP RCPT command
rcpt_param_orcpt The value of the ORCPT parameter from the LMTP RCPT command
rcpt_param_orcpt_type The address type, typically rfc822, of the ORCPT parameter for the LMTP RCPT command

DNS

Events emitted from Dovecot’s internal DNS client.

dns_worker_request_started

Field Description
No event specific fields defined

dns_request_started

Field Description
No event specific fields defined

dns_worker_request_finished

Field Description
error Human readable error
error_code Error code usable with net_gethosterror()

dns_request_finished

Field Description
error Human readable error
error_code Error code usable with net_gethosterror()

SQL

Events emitted by Dovecot’s internal SQL library.

Note

This includes queries sent to Cassandra.

sql_query_finished

Field Description
error Human readable error
error_code Error code (if available)
query_first_word First word of the query (e.g. SELECT)

sql_transaction_finished

Field Description
error Human readable error
error_code Error code (if available)

sql_connection_finished

Field Description
No event specific fields defined

SMTP Server

These events are emitted by Dovecot’s internal lib-smtp library.

Connection

Common fields:

Field Description
Inherits from environment (LDA, LMTP or IMAP)
protocol The protocol used by the connection; i.e., either “smtp” or “lmtp”.

Command

Common fields:

Field Description
Inherits from connection
cmd_name

name of the command

New in version v2.3.9.

smtp_server_command_started

The command is received from the client.

smtp_server_command_finished

The command is finished. Either a success reply was sent for it or it failed somehow.

Field Description
status_code SMTP status code for the (first) reply. This is = 9000 for aborted commands (e.g., when the connection is closed prematurely).
enhanced_code SMTP enhanced status code for the (first) reply. This is “9.0.0” for aborted commands (e.g., when the connection is closed prematurely).
error Error message for the reply. There is no field for a success message.

Transaction

Common fields:

Field Description
Normally inherits from connection
transaction_id Transaction ID used by the server for this transaction (this ID is logged, mentioned in the DATA reply and part of the “Received:” header).
mail_from Sender address.
mail_param_auth The value of the AUTH parameter for the MAIL command.
mail_param_body The value of the BODY parameter for the MAIL command.
mail_param_envid The value of the ENVID parameter for the MAIL command.
mail_param_ret The value of the RET parameter for the MAIL command.
mail_param_size The value of the SIZE parameter for the MAIL command.
data_size The number data of bytes received from the client. This field is only present when the transaction finished receiving the DATA command.
smtp_server_transaction_started

The transaction is started.

smtp_server_transaction_finished

Transaction is finished or failed.

Field Description
status_code SMTP status code for the (first failure) reply. This is = 9000 for aborted transactions (e.g., when the connection is closed prematurely).
enhanced_code SMTP enhanced status code for the (first failure) reply. This is “9.0.0” for aborted transactions (e.g., when the connection is closed prematurely).
error Error message for the first failure reply. There is no field for a success message.
recipients Total number of recipients.
recipients_aborted The number of recipients that got aborted before these could either finish or fail. This means that the transaction failed early somehow while these recipients were still being processed by the server.
recipients_denied The number of recipients denied by the server using a negative reply to the RCPT command.
recipients_failed The number of recipients that failed somehow (includes denied recipients, but not aborted recipients).
recipients_succeeded The number of recipients for which the transaction finally succeeded.
is_reset The transaction was reset (RSET) rather than finishing with a DATA/BDAT command as it normally would. This happens when client side issues the RSET command. Note that a reset event is a success (no error field is present).

Recipient

Common fields:

Field Description
Inherits from transaction
rcpt_to Recipient address
rcpt_param_notify The value of the NOTIFY parameter for the RCPT command.
rcpt_param_orcpt The address value of the ORCPT parameter for the RCPT command.
rcpt_param_orcpt_type The address type (typically “rfc822”) of the ORCPT parameter for the RCPT command.
smtp_server_transaction_rcpt_finished

The transaction is finished or failed for this particular recipient. When successful, this means the DATA command for the transaction yielded success for that recipient (even for SMTP this event is generated for each recipient separately). Recipients can fail at various stages, particularly at the actual RCPT command where the server can deny the recipient.

Field Description
status_code SMTP status code for the reply. This is = 9000 for aborted transactions (e.g., when the connection is closed prematurely).
enhanced_code SMTP enhanced status code for the reply. This is “9.0.0” for aborted transactions (e.g., when the connection is closed prematurely).
error Error message for the reply if it is a failure. There is no field for a success message.

SMTP Submit

These events are emitted by Dovecot’s internal lib-smtp library when sending mails.

Common fields

Field Description
Inherits from provided parent event
mail_from The envelope sender for the outgoing message.
recipients The number of recipients for the outgoing message.
data_size The size of the outgoing message.

smtp_submit_started

Started message submission.

smtp_submit_finished

Finished the message submission.

Field Description
error Error message for submission failure.

Push notifications

Field Description
Inherits from mail user
No event specific fields defined

Push notification event was sent.

Pigeonhole

Sieve

New in version 2.3.9.

Events emitted by sieve scripts.

Common fields

Field Description
Inherits from environment (LDA, LMTP or IMAP)
user Username of the user

Sieve execute

Common fields

Field Description
Inherits from sieve
message_id The message-id of the message being filtered.
mail_from Envelope sender address if available.
rcpt_to Envelope recipient address if available.

Sieve runtime

Common fields

Field Description
Inherits from sieve-execute
script_name The name of the Sieve script as it is visible to the user.
script_location The full location string of the Sieve script.
binary_path The path of the Sieve binary being executed (if it is not only in memory).
error If present, this field indicates that the script execution has failed. The error message itself is very simple.

sieve_runtime_script_started

Started evaluating a Sieve script.

sieve_runtime_script_finished

Finished evaluating a Sieve script

Sieve action

Field Description
Inherits from sieve-execute
action_name The name of the Sieve action.
action_script_location The location string for this Sieve action (a combination of “<script-name>: line <number>”.
redirect_target The target address for the redirect action.
notify_target The list of target addresses for the notify action.
report_target The target address for the report action.
report_type The feedback type for the report action.
fileinto_mailbox The target mailbox for the fileinto/keep action.
pipe_program The name of the program being executed by the pipe action.

sieve_action_finished

The action was executed successfully. The following actions can occur.

action_name=discard
The discard action was executed successfully (only has an effect when no explicit keep is executed).
action_name=redirect
The redirect action was executed successfully.
action_name=reject
The reject action was executed successfully.
action_name=notify
The notify action was executed successfully (either from the notify or the enotify extension).
action_name=vacation
The vacation action was executed successfully.
action_name=report
The report action (from vnd.dovecot.report extension) was executed successfully.
action_name=fileinto
The fileinto action was executed successfully.
action_name=keep
The keep action was executed successfully (maps to fileinto internally, so the fields are identical).
action_name=pipe
The pipe action (from vnd.dovecot.pipe extension) was executed successfully.

Sieve storage

Events emitted by sieve storage.

Common fields

Field Description
Inherits from sieve
storage_driver The driver name of the Sieve storage (‘file’, ‘ldap’ or ‘dict’)
script_location The location string for the Sieve script.
error Error message for when storage operation has failed.

sieve_script_opened

Opened a Sieve script for reading (e.g. for ManageSieve GETSCRIPT or compiling it at delivery).

sieve_script_closed

Closed a Sieve script (after reading it).

sieve_script_deleted

Deleted a Sieve script.

sieve_script_activated

Activated a Sieve script.

sieve_script_renamed

Renamed a Sieve script.

Field Description
old_script_name Old name of the Sieve script
new_script_name New name for the Sieve script

sieve_storage_save_started

Started saving a Sieve script.

Field Description
script_name Name of the Sieve script

sieve_storage_save_finished

Finished saving a Sieve script.

Field Description
script_name Name of the Sieve script

Managesieve

Eventes emitted by the ManageSieve process.

Field Description
Inherits from client event
cmd_name Name of the ManageSieve command.
cmd_name Arguments for the ManageSieve command.
error Error message for when the command failed.

managesieve_command_finished

Finished the ManageSieve command.

Field Description
script_name Name for the Sieve script this command operated on (if any).
old_script_name Old name of the Sieve script (only set for RENAMESCRIPT).
new_script_name New name for the Sieve script (only set for RENAMESCRIPT).
compile_errors The number of compile errors that occurred (only set for PUTSCRIPT, CHECKSCRIPT and SETACTIVE when compile fails).
compile_warnings The number of compile warnings that occurred (only set for PUTSCRIPT, CHECKSCRIPT and SETACTIVE when script is compiled).

obox

obox plugin

Index merging

Events emitted by the new index merging (metacache_index_merging=v2).

Field Description
Inherits from mailbox
No event specific fields defined
obox_index_merge_started

Mailbox index merging was started.

obox_index_merge_finished

Mailbox index merging was finished.

obox_index_merge_uidvalidity_changed

Index merging required changing the mailbox’s IMAP UIDVALIDITY.

obox_index_merge_uids_renumbered

Index merging required changing some mails’ IMAP UIDs because they conflicted between the two indexes.

Field Description
renumber_count Number of UIDs that were renumbered
obox_index_merge_skip_uid_renumbering

Index merging should have renumbered UIDs due to conflicts, but there were too many of them (more than metacache_merge_max_uid_renumbers), so no renumbering was done after all.

Field Description
renumber_count Number of UIDs that should have been renumbered