libESMTP API ReferenceCopyright © 2001-2011 Brian Stafford
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Abstract
This document describes the libESMTP programming interface. The libESMTP API is intended for use as an ESMTP client within a Mail User Agent (MUA) or other program that wishes to submit mail to a preconfigured Message Submission Agent (MSA).
Table of Contents
This document is believed to be accurate but may not necessarily reflect actual behaviour; to quote The Hitch Hikers' Guide to the Galaxy,
Much of it is apocryphal or, at the very least, wildly inaccurate. However, where it is inaccurate, it is definitively inaccurate.
If in doubt, consult the source.
For the most part, the libESMTP API is a relatively thin layer over SMTP protocol operations, that is, most API functions and their arguments are similar to the corresponding protocol commands. Further API functions manage a callback mechanism which is used to read messages from the application and to report protocol progress to the application. The remainder of the API is devoted to reporting on a completed SMTP session.
Although the API closely models the protocol itself, libESMTP relieves the programmer of all the work needed to properly implement RFC 5321 (formerly RFC2821, formerly RFC 821) and avoids many of the pitfalls in typical SMTP implementations. It constructs SMTP commands, parses responses, provides socket buffering and pipelining, where appropriate provides for TLS connections and provides a failover mechanism based on DNS allowing multiple redundant MSAs. Furthermore, support for the SMTP extension mechanism is incorporated by design rather than as an afterthought.
There is limited support for processing RFC 5322 message headers. This is intended to ensure that messages copied to the SMTP server have their correct complement of headers. Headers that should not be present are stripped and reasonable defaults are provided for missing headers. In addition, the header API allows the defaults to be tuned and provides a mechanism to specify message headers when this might be difficult to do directly in the message data.
libESMTP does not implement MIME [RFC 2045] since MIME is, in the words of RFC 2045, “orthogonal” to RFC 5322. The developer is expected to use a separate library to construct MIME documents or the application should construct them directly. libESMTP ensures that top level MIME headers are passed unaltered and the header API functions are guaranteed to fail if any header in the name space reserved for MIME is specified, thus ensuring that MIME documents are not accidentally corrupted.
libESMTP supports the following SMTP extensions. Those extensions which are useful only in Message Transport Agents (MTA) will not be implemented in libESMTP.
Please note that certain SMTP extensions are processed internally to libESMTP and do not require corresponding API functions.
To use the libESMTP API, include libesmtp.h.
Declarations for deprecated symbols must be requested explicitly;
define the macro LIBESMTP_ENABLE_DEPRECATED_SYMBOLS
to be non-zero before including libesmtp.h.
Internally libESMTP creates and maintains structures to track the state of an SMTP protocol session. Opaque pointers to these structures are passed back to the application by the API and must be supplied in various other API calls. The API provides for a callback functions or a simple event reporting mechanism as appropriate so that the application can provide data to libESMTP or track the session's progress. Further API functions allow the session status to be queried after the event. The entire SMTP protocol session is performed by only one function call.
All structures and pointers maintained by libESMTP are opaque, that is, the internal detail of libESMTP structures is not made available to the application. Object oriented programmers may wish to regard the pointers as instances of private classes within libESMTP.
Three pointer types are declared as follows:
typedef struct smtp_session *smtp_session_t; typedef struct smtp_message *smtp_message_t; typedef struct smtp_recipient *smtp_recipient_t;
LibESMTP is thread-aware, however the application is responsible for observing the restrictions below to ensure full thread safety.
Do not access a smtp_session_t, smtp_message_t
or smtp_recipient_t from more than one thread at a time.
A mutex can be used to protect API calls
if the application logic cannot guarantee this.
It is especially important to observe this restriction during a call to
smtp_start_session.
It is advisable for your application to catch or ignore SIGPIPE. libESMTP sets timeouts as it progresses through the protocol. In addition the remote server might close its socket at any time. Consequently libESMTP may sometimes try to write to a socket with no reader. Catching or ignoring SIGPIPE ensures the application isn't killed accidentally when this happens during the protocol session.
Code similar to the following may be used to do this:
#include <signal.h>
void
ignore_sigpipe (void)
{
struct sigaction sa;
sa.sa_handler = SIG_IGN;
sigemptyset (&sa.sa_mask);
sa.sa_flags = 0;
sigaction (SIGPIPE, &sa, NULL);
}
smtp_create_session — create SMTP session descriptor
smtp_session_t smtp_create_session( | void); |
smtp_add_message — add a message to an SMTP session
smtp_message_t smtp_add_message( | smtp_session_t session); |
smtp_enumerate_messages — enumerate messages in an SMTP session
typedef void (*smtp_enumerate_messagecb_t)( | smtp_message_t message, |
void *arg); |
int smtp_enumerate_messages( | smtp_session_t session, |
| smtp_enumerate_messagecb_t cb, | |
void *arg); |
smtp_set_hostname — set the name of the localhost
int smtp_set_hostname( | smtp_session_t session, |
const char *hostname); |
smtp_set_server — set the hostname of the message submission server
smtp_set_server( | smtp_session_t session, |
const char *hostport); |
Set the host name and service for the client connection. This is specified
in the format host.example.org[:service] with no
whitespace surrounding the colon if service is specified.
service may be a name from
/etc/services or a decimal port number. If not
specified the port defaults to 587. Host and service name validity is
not checked until an attempt to connect to the remote host.
The default port number is set to 587 since this is the port that should
be used for mail submission, see RFC 4409. By choosing this default
now, the API does not change behaviour unexpectedly in the future as
use of the new standard becomes commonplace. The hostport nototion
simplifies things for the application, the user can type
localhost:smtp or
localhost:25 where the application expects a host
name.
smtp_set_reverse_path — set the reverse path mailbox
smtp_set_reverse_path( | smtp_message_t message, |
const char *mailbox); |
Set the reverse path (envelope sender) mailbox address.
mailbox must be an address using the syntax
specified in RFC 5321. If a null reverse path is required, specify
mailbox as NULL or
"".
The reverse path mailbox address is used to generate a From:
header when the message neither contains a From: header
nor has one been specified using smtp_set_header.
It is strongly reccommended that the message supplies a From: header specifying a single mailbox or a Sender: header and a From: header specifying multiple mailboxes or that the libESMTP header APIs are used to create them.
smtp_add_recipient — add a recipient to a message
smtp_recipient_t smtp_add_recipient( | smtp_message_t message, |
const char *mailbox); |
Add a recipient to the message. mailbox must be an address
using the syntax specified in RFC 5321.
If neither the message contains a To: header nor a
To: is specified using smtp_set_header,
one header will be automatically generated using the list
of envelope recipients.
It is strongly reccommended that the message supplies To:, Cc: and Bcc: headers or that the libESMTP header APIs are used to create them.
smtp_enumerate_recipients — enumerate message recipients
typedef void (*smtp_enumerate_recipientcb_t)( | smtp_recipient_t recipient, |
| const char *mailbox, | |
void *arg); |
int smtp_enumerate_recipients( | smtp_message_t message, |
| smtp_enumerate_recipientcb_t cb, | |
void *arg); |
smtp_set_header — set an RFC 5322 message header
int smtp_set_header( | smtp_message_t message, |
| const char *header, | |
...); |
Set an RFC 5322 message header.
If a value is supplied using smtp_set_header the header
is required to be present in the message. If the Hdr_OVERRIDE
option is not set a value supplied in the message is used unchanged;
otherwise the value in the message is replaced.
Headers in the message not corresonding to a default header action or set
with smtp_set_header are passed unchanged.
This section lists the additional function arguments for individual RFC 5322 headers.
const char *value
Headers not specifically known to libESMTP are treated as simple string values.
const time_t *value
A pointer to a time_t supplies the value for this header. The time pointed to is copied and is formatted according to RFC 5322 when the value is required.
The Date: header is automatically generated if one is not supplied either in the message or via the API.
const char *value
A string value is supplied which is the message identifier.
If NULL is supplied, a value is automatically generated.
At present there is no way for the application to retrieve the
automatically generated value.
const char *phrase, const char *mailbox
phrase is free format text which is usually the
real name of the recipient specified in mailbox, for example
Brian Stafford.
mailbox is as defined in RFC 5322, for example
brian@stafford.uklinux.net.
The From: header is automatically generated if one is not
supplied either in the message or via the API.
Refer to smtp_set_reverse_path for a
description of the action taken by libESMTP.
const char *phrase, const char *address
phrase is free format text which is usually the
real name of the recipient specified in address,
for example Brian Stafford.
address is as defined in RFC 5322, for example
brian@stafford.uklinux.net.
These headers may be set multiple times, however only one copy of each
header listing all the values is actually created in the message.
The To: header is automatically generated if one is not
supplied either in the message or via the API. Refer to
smtp_add_recipient for a description of the action taken
by libESMTP.
Certain headers may not be set using this call. In particular, MIME headers cannot be set, the values in the message are always used. This is because MIME [RFC 2045 - RFC 2049] is "orthogonal" to RFC 5322 and libESMTP strives to preserve this condition. In addition, headers added to a message at delivery time such as Return-Path: are always deleted from the message.
Certain headers may be specified multiple times and generate a single
header listing all values specified. If the header does not permit a
list of values, calls to smtp_set_header but the
first for a given header will fail.
smtp_set_header_option — set options for message header processing
int smtp_set_header_option( | smtp_message_t message, |
| const char *header, | |
| enum header_option option, | |
...); |
enum header_option
{
Hdr_OVERRIDE,
Hdr_PROHIBIT
};
Set an RFC 5322 message header option.
Header Options
Normally, a header set by smtp_set_header is used
as a default if one is not supplied in the message. When Hdr_OVERRIDE
is set, the value supplied in the API overrides the value in the
message.
libESMTP generates certain headers automatically if not present in the message. This is the default behaviour for headers that are RECOMMENDED but not REQUIRED by RFC 5322, such as Message-Id:. Setting Hdr_PROHIBIT ensures the transmitted message does not contain the named header. If the header is REQUIRED by RFC 5322, the API will fail.
smtp_set_resent_headers
int smtp_set_resent_headers( | smtp_message_t message, |
int onoff); |
smtp_set_timeout
long smtp_set_timeout( | smtp_session_t session, |
| int which, | |
long value); |
smtp_option_require_all_recipients
int smtp_option_require_all_recipients( | smtp_session_t session, |
int state); |
smtp_set_messagecb — set callback for reading the message from an application
typedef const char *(smtp_messagecb_t)( | void **buf, |
| int *len, | |
void *arg); |
int smtp_set_messagecb( | smtp_message_t message, |
| smtp_messagecb_t cb, | |
void *arg); |
Set a callback function to read an RFC 5322 formatted message from the application.
The callback is used for two purposes. If len is
set to NULL the callback is to rewind the message.
The return value is not used. If len is not
NULL, the callback returns a pointer to the start
of the message buffer and sets the *len to the
number of octets of data in the buffer.
The callback is called repeatedly until the entire message has
been processed. When all the message data has been read the
callback should return NULL.
If the callback requires a buffer for the message data, it should
allocate one with malloc and place the pointer in *buf,
otherwise *buf must be set to NULL. The buffer is freed
automatically by libESMTP.
smtp_set_message_fp
int smtp_set_message_fp( | smtp_message_t message, |
FILE *fp); |
smtp_set_message_str
int smtp_set_message_str( | smtp_message_t message, |
const char *string); |
smtp_set_eventcb — set callback for reporting events to the applciation
typedef void (*smtp_eventcb_t)( | smtp_session_t session, |
| int event_no, | |
| void *arg, | |
...); |
int smtp_set_eventcb( | smtp_session_t session, |
| smtp_eventcb_t cb, | |
void *arg); |
enum
{
/* Protocol progress */
SMTP_EV_CONNECT,
SMTP_EV_MAILSTATUS,
SMTP_EV_RCPTSTATUS,
SMTP_EV_MESSAGEDATA,
SMTP_EV_MESSAGESENT,
SMTP_EV_DISCONNECT,
SMTP_EV_SYNTAXWARNING,
/* Protocol extension progress */
SMTP_EV_ETRNSTATUS,
/* Required extensions */
SMTP_EV_EXTNA_DSN,
SMTP_EV_EXTNA_8BITMIME,
SMTP_EV_EXTNA_STARTTLS,
SMTP_EV_EXTNA_ETRN,
SMTP_EV_EXTNA_CHUNKING,
SMTP_EV_EXTNA_BINARYMIME,
/* Extensions specific events */
SMTP_EV_DELIVERBY_EXPIRED,
/* STARTTLS */
SMTP_EV_WEAK_CIPHER,
SMTP_EV_STARTTLS_OK,
SMTP_EV_INVALID_PEER_CERTIFICATE,
SMTP_EV_NO_PEER_CERTIFICATE,
SMTP_EV_WRONG_PEER_CERTIFICATE,
SMTP_EV_NO_CLIENT_CERTIFICATE,
SMTP_EV_UNUSABLE_CLIENT_CERTIFICATE,
SMTP_EV_UNUSABLE_CA_LIST
};
smtp_set_monitorcb — set callback for tracing the SMTP protocol session
typedef void (*smtp_monitorcb_t)( | const char *buf, |
| int buflen, | |
| int writing, | |
void *arg); |
int smtp_set_monitorcb( | smtp_session_t session, |
| smtp_monitorcb_t cb, | |
| void *arg, | |
int headers); |
/* Protocol monitor callback. Values for writing */
#define SMTP_CB_READING 0
#define SMTP_CB_WRITING 1
#define SMTP_CB_HEADERS 2
Set a callback function to monitor the SMTP session with the server. The callback is called with packets of data either transmitted to or received from the server. When writing is non-zero, data is being written to the remote host otherwise the data is being read from the remote host. In the event that an encrypted connection to the server is in use, the monitor callback will show the clear text.
When the callback is used, the data passed in buf
corresponds to the buffered packet of data written to or read from the
server. This may contain more than one protocol command or response.
The content of the DATA (or BDAT) command is not passed back to the
application since this is typically large and possibly binary. However,
it may be useful to view the message headers. If
headers is non-zero the callback will be used to
display the message headers. In this case, the value of
writing is set to CB_HEADERS
(2) instead of CB_WRITING (1) so that the
application can distinguish headers from other data sent to the SMTP
server. The callback is passed each header one at a time and in this
case the data passed back to the application does not reflect the actual
buffering of the data on-the-wire.
Note that headers within MIME parts will not be returned, only the message headers.
smtp_set_application_data — attach application data to libESMTP structures
void *smtp_set_application_data( | smtp_session_t session, |
void *data); |
void *smtp_get_application_data( | smtp_session_t session); |
void *smtp_message_set_application_data( | smtp_message_t message, |
void *data); |
void *smtp_message_get_application_data( | smtp_message_t message); |
void *smtp_recipient_set_application_data( | smtp_recipient_t recipient, |
void *data); |
void *smtp_recipient_get_application_data( | smtp_recipient_t recipient); |
smtp_start_session — run an SMTP protocol session
int smtp_start_session( | smtp_session_t session); |
Initiate a mail submission session with an SMTP server.
This connects to an SMTP server and transfers the messages in the session. The SMTP envelope is constructed using the message and recipient parameters set up previously. The message callback is then used to read the message contents to the server. As the RFC 5322 headers are read from the application, they may be processed. Header processing terminates when the first line containing only CR-LF is encountered. The remainder of the message is copied verbatim.
This call is atomic in the sense that a connection to the server is made only when this is called and is closed down before it returns, i.e. there is no connection to the server outside this function.
smtp_destroy_session — release all resources associated with an SMTP session
int smtp_destroy_session( | smtp_session_t session); |
smtp_version — retrieve libESMTP version information
int smtp_version( | void *buf, |
| size_t len, | |
int what); |
smtp_errno — get error code for most recent API call
int smtp_errno( | ); |
The following error codes are defined:
#define SMTP_ERR_NOTHING_TO_DO
#define SMTP_ERR_DROPPED_CONNECTION
#define SMTP_ERR_INVALID_RESPONSE_SYNTAX
#define SMTP_ERR_STATUS_MISMATCH
#define SMTP_ERR_INVALID_RESPONSE_STATUS
#define SMTP_ERR_INVAL
#define SMTP_ERR_EXTENSION_NOT_AVAILABLE
/* libESMTP versions of some getaddrinfo error numbers */
#define SMTP_ERR_EAI_ADDRFAMILY
#define SMTP_ERR_EAI_NODATA
#define SMTP_ERR_EAI_FAIL
#define SMTP_ERR_EAI_AGAIN
#define SMTP_ERR_EAI_MEMORY
#define SMTP_ERR_EAI_FAMILY
#define SMTP_ERR_EAI_BADFLAGS
#define SMTP_ERR_EAI_NONAME
#define SMTP_ERR_EAI_SERVICE
#define SMTP_ERR_EAI_SOCKTYPE
#define SMTP_ERR_UNTERMINATED_RESPONSE
#define SMTP_ERR_CLIENT_ERROR
SMTP_ERR_INVAL means that an API was called with invalid arguments.
Functions which retrieve SMTP status codes return a pointer to the following structure which contains the status information.
struct smtp_status
{
int code; /* SMTP protocol status pre */
const char *text; /* Text from the server */
int enh_class; /* RFC 2034 enhanced status triplet */
int enh_subject;
int enh_detail;
};
typedef struct smtp_status smtp_status_t;
smtp_message_transfer_status
const smtp_status_t *smtp_message_transfer_status( | smtp_message_t message); |
Retrieve the message transfer success/failure status from a
previous SMTP session. This includes SMTP status codes, RFC
2034 enhanced status codes, if available, and text from the
server describing the status. If a message is marked with a
success or permanent failure status, it will not be resent if
smtp_start_session
is called again.
smtp_reverse_path_status
const smtp_status_t *smtp_reverse_path_status( | smtp_message_t message); |
smtp_message_reset_status
int smtp_message_reset_status( | smtp_message_t recipient); |
smtp_recipient_status
const smtp_status_t *smtp_recipient_status( | smtp_recipient_t recipient); |
Retrieve the recipient success/failure status from a previous SMTP
session. This includes SMTP status codes, RFC 2034 enhanced status
codes, if available and text from the server describing the status.
If a recipient is marked with a success or permanent failure status,
it will not be resent if smtp_start_session is
called again, however it may be used when generating To:
or Cc: headers if required.
smtp_recipient_check_complete
int smtp_recipient_check_complete( | smtp_recipient_t recipient); |
smtp_recipient_reset_status
int smtp_recipient_reset_status( | smtp_recipient_t recipient); |
The following APIs relate to SMTP extensions. Note that not all supported extensions require corresponding API functions.
smtp_dsn_set_ret
int smtp_dsn_set_ret( | smtp_message_t message, |
enum ret_flags flags); |
enum ret_flags { Ret_NOTSET, Ret_FULL, Ret_HDRS };
smtp_dsn_set_envid
int smtp_dsn_set_envid( | smtp_message_t message, |
const char *envid); |
smtp_dsn_set_notify
int smtp_dsn_set_notify( | smtp_recipient_t recipient, |
enum notify_flags flags); |
enum notify_flags
{
Notify_NOTSET,
Notify_NEVER,
Notify_SUCCESS,
Notify_FAILURE,
Notify_DELAY
};
smtp_dsn_set_orcpt
int smtp_dsn_set_orcpt( | smtp_recipient_t recipient, |
| const char *address_type, | |
const char *address); |
Set the DSN ORCPT option.
Included only for completeness. This DSN option is only used when performing mailing list expansion or similar situations when the envelope recipient no longer matches the recipient for whom the DSN is to be generated. Probably only useful to an MTA and should not normally be used by an MUA or other program which submits mail.
smtp_8bitmime_set_body
int smtp_8bitmime_set_body( | smtp_message_t message, |
enum e8bitmime_body body); |
enum e8bitmime_body
{
E8bitmime_NOTSET,
E8bitmime_7BIT,
E8bitmime_8BITMIME
};
The 8-bit MIME extension allows an SMTP client to declare the message
body is either in strict conformance with RFC 5322
(E8bitmime_7BIT) or that it is a MIME document
where some or all of the MIME parts use 8bit encoding
(E8bitmime_8BITMIME). If this API sets the body
type to other than E8bitmime_NOTSET, libESMTP will
use the event callback to notify the application if the MTA does not
support the 8BITMIME extension.
The SMTP ETRN extension is used to request a remore MTA to start its delivery queue for the specified domain. If the application requests the use if the ETRN extension and the remote MTA does not list ETRN, libESMTP will use the event callback to notify the application.
smtp_etrn_add_node
typedef struct smtp_etrn_node *smtp_etrn_node_t;
smtp_etrn_node_t smtp_etrn_add_node( | smtp_session_t session, |
| int option, | |
const char *node); |
smtp_etrn_enumerate_nodes
typedef void (*smtp_etrn_enumerate_nodecb_t)( | smtp_etrn_node_t node, |
| int option, | |
| const char *domain, | |
void *arg); |
int smtp_etrn_enumerate_nodes( | smtp_session_t session, |
| smtp_etrn_enumerate_nodecb_t cb, | |
void *arg); |
smtp_etrn_node_status
const smtp_status_t *smtp_etrn_node_status( | smtp_etrn_node_t node); |
smtp_etrn_set_application_data
void *smtp_etrn_set_application_data( | smtp_etrn_node_t node, |
void *arg); |
void *smtp_etrn_get_application_data( | smtp_etrn_node_t node); |
smtp_auth_set_context
#include <auth-client.h>
#include <libesmtp.h>
int smtp_auth_set_context( | smtp_session_t session, |
auth_context_t context); |
Enable the SMTP AUTH verb if context is not
NULL or disable it when context is NULL.
The authentication API is described separately.
When enabled and the SMTP server advertises the AUTH extension, libESMTP
will attempt to authenticate to the SMTP server before transferring
any messages. context must be obtained from the SASL (RFC 4422) client
library API defined in auth-client.h.
A separate authentication context must be created for each SMTP session.
The application is responsible for destroying context. The application
should either call smtp_destroy_session or call
smtp_auth_set_context with context set to
NULL before doing so.
If OpenSSL is available when building libESMTP, support for the STARTTLS extension can be enabled. If support is not enabled, the following APIs will always fail.
smtp_starttls_enable
enum starttls_option
{
Starttls_DISABLED,
Starttls_ENABLED,
Starttls_REQUIRED
};
int smtp_starttls_enable( | smtp_session_t session, |
enum starttls_option how); |
smtp_starttls_set_ctx
#include <openssl/ssl.h>
#include <libesmtp.h>
int smtp_starttls_set_ctx( | smtp_session_t session, |
SSL_CTX *ctx); |