10.3 The Callout Protocol

This section describes the protocol used to communicate with the calloutd server.

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:.

Command: vrfy email [parameter=value]

Adds email to the queue of email addresses to be verified. Available parameters are:

callout parameter: mode

Sets verification mode for this email address. Available modes are:

mxfirst

default

The default mode.

If the 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.

mxonly

Query MX servers for the domain specified with the host option.

hostonly

Query the server whose name or IP address is supplied with the host option.

hostfirst

The reverse of mxfirst: first query the host, then the MX servers. The domain must be specified using the host option.

callout parameter: host

Supplies the domain name for mode=mxonly, and host name or IP address for mode=hostfirst and mode=hostonly. The use of this keyword with any of these modes is mandatory.

callout parameter: ehlo

Supplies the value to use as the argument to the SMTP EHLO command.

callout parameter: mailfrom

Supplies the value to use in the SMTP MAIL FROM command.

callout parameter: starttls

Controls whether to use SMTP STARTTLS command if the server offers it. Allowed values are:

never

Never use STARTTLS.

always

Always use STARTTLS.

ondemand

Use STARTTLS only if MAIL FROM: command fails with code 530 (authorization failed). This is the default.

On success, the server replies with ‘OK’, followed by a non-negative session ID for that email:

C: VRFY gray@example.org
S: OK 0000000001

Command: get arg [arg]

Query value of internal callout parameters. Valid values for arg are:

ehlo

Return the string used as argument to the SMTP EHLO command.

mailfromd

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

Command: sid string

Sets string as session identifier for that session. Example:

C: SID deadbeef
S: OK

Command: timeout connect initial helo mail rcpt rset quit

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

Command: run

Runs callout session for emails registered with the vrfy 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:

INIT remote_name

The calloutd server is establishing communication with the remote SMTP server remote_name.

GRTNG line

calloutd received initial response from the remote server. line is the first line of the reply.

HELO line

calloutd received response to the EHLO (or HELO) command. In case of multiline response, line is the first line.

SENT command

The SMTP command command has been sent to the remote server.

RECV line

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:<gray@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:<gray@example.net>
S: * 0000000001 RECV 450 4.7.0 You are greylisted for 3600 seconds
OK 0000000000=success 0000000001=temp_failure

Command: drop serial

Drop the email with the given serial number from the verification queue. Example:

C: DROP 0000000002
S: OK

Command: quit

Finishes the current session and disconnects from the callout server.

C: QUIT
S: OK bye