Milter API

Library Control Functions
Data Access Functions
Message Modification Functions
Callbacks
Miscellaneous

Library Control Functions

Before handing control to libmilter (by calling smfi_main), a filter may call the following functions to set libmilter parameters. In particular, the filter must call smfi_register to register its callbacks. Each function will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation.

None of these functions communicate with the MTA. All alter the library's state, some of which is communicated to the MTA inside smfi_main.

Function Description

smfi_opensocket Try to create the interface socket.

smfi_register Register a filter.

smfi_setconn Specify socket to use.

smfi_settimeout Set timeout.

smfi_setbacklog Define the incoming listen(2) queue size.

smfi_setdbg Set the milter library debugging (tracing) level.

smfi_stop Cause an orderly shutdown.

smfi_main Hand control to libmilter.

Function	Description
smfi_opensocket	Try to create the interface socket.
smfi_register	Register a filter.
smfi_setconn	Specify socket to use.
smfi_settimeout	Set timeout.
smfi_setbacklog	Define the incoming `listen(2)` queue size.
smfi_setdbg	Set the milter library debugging (tracing) level.
smfi_stop	Cause an orderly shutdown.
smfi_main	Hand control to libmilter.

Data Access Functions

The following functions may be called from within the filter-defined callbacks to access information about the current connection or message.

Function Description

smfi_getsymval Return the value of a symbol.

smfi_getpriv Get the private data pointer.

smfi_setpriv Set the private data pointer.

smfi_setreply Set the specific reply code to be used.

smfi_setmlreply Set the specific multi-line reply to be used.

Function	Description
smfi_getsymval	Return the value of a symbol.
smfi_getpriv	Get the private data pointer.
smfi_setpriv	Set the private data pointer.
smfi_setreply	Set the specific reply code to be used.
smfi_setmlreply	Set the specific multi-line reply to be used.

Message Modification Functions

The following functions change a message's contents and attributes. They may only be called in xxfi_eom. All of these functions may invoke additional communication with the MTA. They will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation. Message data (senders, recipients, headers, body chunks) passed to these functions via parameters is copied and does not need to be preserved (i.e., allocated memory can be freed).

A filter must have set the appropriate flag (listed below) in the description passed to smfi_register to call any message modification function. Failure to do so will cause the MTA to treat a call to the function as a failure of the filter, terminating its connection.

Note that the status returned indicates only whether or not the filter's message was successfully sent to the MTA, not whether or not the MTA performed the requested operation. For example, smfi_addheader, when called with an illegal header name, will return MI_SUCCESS even though the MTA may later refuse to add the illegal header.

Function Description SMFIF_* flag

smfi_addheader Add a header to the message. SMFIF_ADDHDRS

smfi_chgheader Change or delete a header. SMFIF_CHGHDRS

smfi_insheader Insert a header into the message. SMFIF_ADDHDRS

smfi_chgfrom Change the envelope sender address. SMFIF_CHGFROM

smfi_addrcpt Add a recipient to the envelope. SMFIF_ADDRCPT

smfi_addrcpt_par Add a recipient including ESMTP parameter to the envelope. SMFIF_ADDRCPT_PAR

smfi_delrcpt Delete a recipient from the envelope. SMFIF_DELRCPT

smfi_replacebody Replace the body of the message. SMFIF_CHGBODY

Function	Description	SMFIF_* flag
smfi_addheader	Add a header to the message.	SMFIF_ADDHDRS
smfi_chgheader	Change or delete a header.	SMFIF_CHGHDRS
smfi_insheader	Insert a header into the message.	SMFIF_ADDHDRS
smfi_chgfrom	Change the envelope sender address.	SMFIF_CHGFROM
smfi_addrcpt	Add a recipient to the envelope.	SMFIF_ADDRCPT
smfi_addrcpt_par	Add a recipient including ESMTP parameter to the envelope.	SMFIF_ADDRCPT_PAR
smfi_delrcpt	Delete a recipient from the envelope.	SMFIF_DELRCPT
smfi_replacebody	Replace the body of the message.	SMFIF_CHGBODY

Other Message Handling Functions

The following functions provide special case handling instructions for milter or the MTA, without altering the content or status of the message. They too may only be called in xxfi_eom. All of these functions may invoke additional communication with the MTA. They will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation.

Note that the status returned indicates only whether or not the filter's message was successfully sent to the MTA, not whether or not the MTA performed the requested operation.

Function Description

smfi_progress Report operation in progress.

smfi_quarantine Quarantine a message.

Function	Description
smfi_progress	Report operation in progress.
smfi_quarantine	Quarantine a message.

Callbacks

The filter should implement one or more of the following callbacks, which are registered via smfi_register:

Function Description

xxfi_connect connection info

xxfi_helo SMTP HELO/EHLO command

xxfi_envfrom envelope sender

xxfi_envrcpt envelope recipient

xxfi_data DATA command

xxfi_unknown Unknown SMTP command

xxfi_header header

xxfi_eoh end of header

xxfi_body body block

xxfi_eom end of message

xxfi_abort message aborted

xxfi_close connection cleanup

xxfi_negotiate option negotiattion

Function	Description
xxfi_connect	connection info
xxfi_helo	SMTP HELO/EHLO command
xxfi_envfrom	envelope sender
xxfi_envrcpt	envelope recipient
xxfi_data	DATA command
xxfi_unknown	Unknown SMTP command
xxfi_header	header
xxfi_eoh	end of header
xxfi_body	body block
xxfi_eom	end of message
xxfi_abort	message aborted
xxfi_close	connection cleanup
xxfi_negotiate	option negotiattion

The above callbacks should all return one of the following return values, having the indicated meanings. Any return other than one of the below values constitutes an error, and will cause sendmail to terminate its connection to the offending filter.

Milter distinguishes between recipient-, message-, and connection-oriented routines. Recipient-oriented callbacks may affect the processing of a single message recipient; message-oriented callbacks, a single message; connection-oriented callbacks, an entire connection (during which multiple messages may be delivered to multiple sets of recipients). xxfi_envrcpt is recipient-oriented. xxfi_connect, xxfi_helo and xxfi_close are connection-oriented. All other callbacks are message-oriented.

Return value Description

SMFIS_CONTINUE Continue processing the current connection, message, or recipient.

SMFIS_REJECT For a connection-oriented routine, reject this connection; call xxfi_close.
For a message-oriented routine (except xxfi_eom or xxfi_abort), reject this message.
For a recipient-oriented routine, reject the current recipient (but continue processing the current message).

SMFIS_DISCARD For a message- or recipient-oriented routine, accept this message, but silently discard it.
SMFIS_DISCARD should not be returned by a connection-oriented routine.

SMFIS_ACCEPT For a connection-oriented routine, accept this connection without further filter processing; call xxfi_close.
For a message- or recipient-oriented routine, accept this message without further filtering.

SMFIS_TEMPFAIL Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. For a message-oriented routine (except xxfi_envfrom), fail for this message.
For a connection-oriented routine, fail for this connection; call xxfi_close.
For a recipient-oriented routine, only fail for the current recipient; continue message processing.

SMFIS_SKIP Skip further callbacks of the same type in this transaction. Currently this return value is only allowed in xxfi_body(). It can be used if a milter has received sufficiently many body chunks to make a decision, but still wants to invoke message modification functions that are only allowed to be called from xxfi_eom(). Note: the milter must negotiate this behavior with the MTA, i.e., it must check whether the protocol action SMFIP_SKIP is available and if so, the milter must request it.

SMFIS_NOREPLY Do not send a reply back to the MTA. The milter must negotiate this behavior with the MTA, i.e., it must check whether the appropriate protocol action SMFIP_NR_* is available and if so, the milter must request it. If you set the SMFIP_NR_* protocol action for a callback, that callback must always reply with SMFIS_NOREPLY. Using any other reply code is a violation of the API. If in some cases your callback may return another value (e.g., due to some resource shortages), then you must not set SMFIP_NR_* and you must use SMFIS_CONTINUE as the default return code. (Alternatively you can try to delay reporting the problem to a later callback for which SMFIP_NR_* is not set.)

Return value	Description
SMFIS_CONTINUE	Continue processing the current connection, message, or recipient.
SMFIS_REJECT	For a connection-oriented routine, reject this connection; call xxfi_close. For a message-oriented routine (except xxfi_eom or xxfi_abort), reject this message. For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
SMFIS_DISCARD	For a message- or recipient-oriented routine, accept this message, but silently discard it. SMFIS_DISCARD should not be returned by a connection-oriented routine.
SMFIS_ACCEPT	For a connection-oriented routine, accept this connection without further filter processing; call xxfi_close. For a message- or recipient-oriented routine, accept this message without further filtering.
SMFIS_TEMPFAIL	Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. For a message-oriented routine (except xxfi_envfrom), fail for this message. For a connection-oriented routine, fail for this connection; call xxfi_close. For a recipient-oriented routine, only fail for the current recipient; continue message processing.
SMFIS_SKIP	Skip further callbacks of the same type in this transaction. Currently this return value is only allowed in xxfi_body(). It can be used if a milter has received sufficiently many body chunks to make a decision, but still wants to invoke message modification functions that are only allowed to be called from xxfi_eom(). Note: the milter must negotiate this behavior with the MTA, i.e., it must check whether the protocol action `SMFIP_SKIP` is available and if so, the milter must request it.
SMFIS_NOREPLY	Do not send a reply back to the MTA. The milter must negotiate this behavior with the MTA, i.e., it must check whether the appropriate protocol action `SMFIP_NR_` is available and if so, the milter must request it. If you set the `SMFIP_NR_` protocol action for a callback, that callback must always reply with SMFIS_NOREPLY. Using any other reply code is a violation of the API. If in some cases your callback may return another value (e.g., due to some resource shortages), then you must not set `SMFIP_NR_` and you must use SMFIS_CONTINUE as the default return code. (Alternatively you can try to delay reporting the problem to a later callback for which `SMFIP_NR_` is not set.)

Miscellaneous

Function Description

smfi_version libmilter (runtime) version info

smfi_setsymlist Set the list of macros that the milter wants to receive from the MTA for a protocol stage.

Function	Description
smfi_version	libmilter (runtime) version info
smfi_setsymlist	Set the list of macros that the milter wants to receive from the MTA for a protocol stage.

Constant Description

SMFI_VERSION libmilter (compile time) version info