Previous: invocation-calloutd, Up: calloutd [Contents][Index]
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:.
Adds email to the queue of email addresses to be verified. Available parameters are:
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.
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.
Supplies the value to use as the argument to the SMTP EHLO
command.
Supplies the value to use in the SMTP MAIL FROM
command.
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
Query value of internal callout parameters. Valid values for arg are:
Return the string used as argument to the SMTP EHLO
command.
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 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
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
Previous: invocation-calloutd, Up: calloutd [Contents][Index]