5.21 SMTP Callout Functions

Library Function: number callout_open (string url)

Opens connection to the callout server listening at url. Returns the descriptor of the connection.

Library Function: void callout_close (number fd)

Closes the connection. fd is the file descriptor returned by the previous call to callout_open.

Library Function: number callout_do (number fd, string email [, string rest])

Instructs the callout server identified by fd (a file descriptor returned by a previous call to callout_open) to verify the validity of the email. Optional rest argument supplies additional parameters for the server. It is formatted as a sequence of parameter settings delimited by whitespaces. Each setting is a parameter name and value separated by a ‘=’ sign. See callout parameters, for a discussion of available callout parameters.

Possible return values:

0

Success. The email is found to be valid.

e_not_found

email does not exist.

e_temp_failure

The email validity cannot be determined right now, e.g. because remote SMTP server returned temporary failure. The caller should retry verification later.

e_failure

Some error occurred.

The function will throw the e_callout_proto exception if the remote host doesn’t speak the correct callout protocol.

Upon return, callout_do modifies the following variables:

last_poll_host

Host name or IP address of the last polled SMTP server.

last_poll_greeting

Initial SMTP reply from the last polled host.

last_poll_helo

The reply to the HELO (EHLO) command, received from the last polled host.

last_poll_sent

Last SMTP command sent to the polled host. If nothing was sent, last_poll_sent contains the string ‘nothing’.

last_poll_recv

Last SMTP reply received from the remote host. In case of multi-line replies, only the first line is stored. If nothing was received the variable contains the string ‘nothing’.

The default callout server is defined by the callout-url statement in the configuration file, or by the callout statement in the server milter section (see configuring default callout server. The following functions operate on that server.

Built-in Function: string default_callout_server_url ()

Returns URL of the default callout server.

Library Function: number callout (string email)

Verifies the validity of the email using the default callout server.