General-Purpose Mail Filter
This section describes the protocol used to communicate with the
The protocol works over stream-oriented TCP/IP transport. Either UNIX or IPv4 socket can be used. Commands and responses are terminated by a single CR LF pair. Each command occupies exactly one line. If the server succeeded in executing the command, it replies with a line starting with the word ‘OK’. Depending on the command, this keyword may be followed by a single space character and additional information. More information can be returned in unsolicited replies before the ‘OK’ line. Each unsolicited reply line starts with and asterisk followed by a single horizontal space character.
On error, the server replies with ‘NO’ followed by a horizontal space character and human-readable description of the problem.
The valid commands are discussed below. In examples illustrating the commands, the lines sent by the client are prefixed with C:, and lines sent by the server are prefixed with S:.
Adds email to the queue of email addresses to be verified. Available options are:
Sets verification mode for this email address. Available modes are:
The default mode.
host option is also given, its argument is taken as
the domain name. Otherwise, domain part of email is used.
The verification goes as follows. First, determine MX servers for that domain. Query each of them in order of increasing priority. First of them that replies determines the result of the test.
If no MX servers are defined for that domain, look for its ‘A’ record. If available, run SMTP probe on that IP.
Query MX servers for the domain specified with the
Query the server whose name or IP address is supplied with the
The reverse of
mxfirst: first query the host, then the MX
servers. The domain must be specified using the
Supplies the domain name for
mxonly and mode, and host name or
IP address for
hostonly modes. The use of
this keyword with any of these modes is mandatory.
Use string as the argument to the SMTP
Use email in the SMTP
MAIL FROM command.
On success, the server replies with ‘OK’, followed by a non-negative session ID for that email:
C: VRFY email@example.com S: OK 0000000001
Query value of internal callout parameters. Valid values for arg are:
Return the string used as argument to the SMTP
Return the email address that is used in the SMTP
MAIL FROM command.
On success, the server returns the requested value (if found) in an unsolicited reply:
C: GET ehlo timeout S: * ehlo=example.net S: OK
Sets string as session identifier for that session. Example:
C: SID deadbeef S: OK
Sets timeouts for various stages of SMTP session. On success, ‘OK’ is returned.
C: timeout 300 300 300 600 300 300 120 S: OK timeouts set
Runs callout session for emails registered with the
command. On success, results of the check are returned after the
‘OK’ keyword in a whitespace-separated list of
‘id=result’ pairs. In each pair, id is its
identifier as returned in the reply to the
VRFY command and
result is one of the following result strings: ‘success’,
‘not_found’, ‘failure’, ‘temp_failure’, ‘timeout’.
Additional information about each callout session is returned in unsolicited replies. Each such reply is prefixed with the email identifier and callout stage name. Stage names are:
calloutd server is establishing communication with the
remote SMTP server remote_name.
calloutd received initial response from the remote server.
line is the first line of the reply.
calloutd received response to the
HELO) command. In case of multiline response, line is
the first line.
The SMTP command command has been sent to the remote server.
The remote server returned line in response. In case of multiline response, line is the first line.
Example of verification session:
C: RUN S: * 0000000000 INIT mx.example.org S: * 0000000000 GRTNG 220 mx.example.org ESMTP Ready S: * 0000000000 HELO 250-mx.example.org Hello tester S: * 0000000000 SENT RCPT TO:<firstname.lastname@example.org> S: * 0000000000 RECV 250 Accepted S: * 0000000001 INIT foo.example.net S: * 0000000001 GRTNG 220 foo ESMTP server ready S: * 0000000001 HELO 250-foo.example.net Hello S: * 0000000001 SENT RCPT TO:<email@example.com> S: * 0000000001 RECV 450 4.7.0 You are greylisted for 3600 seconds OK 0000000000=success 0000000001=temp_failure
Drop the email with the given serial number from the verification queue. Example:
C: DROP 0000000002 S: OK
Finishes the current session and disconnects from the callout server.
C: QUIT S: OK bye
This document was generated on January 3, 2019 using makeinfo.Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.