Brian Stafford

brian@stafford.uklinux.org

2001,2002 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. 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). libESMTP is currently under development. Consequently certain parts of the API are subject to change between releases of the library and certain APIs and SMTP extensions have not yet been fully implemented. Furthermore, the descriptions in this document do not necessarily reflect currently implemented functionality. For now, regard this document more as a statement of intent than an accurate description, or 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. The API and documentation will stabilise as version 1.0 approaches. 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 2821 (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 2822 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 orthogonal to RFC 2822. It is expected that a separate library will be used to construct MIME documents. 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. [RFC 1893] ENHANCEDSTATUSCODES [RFC 2920] PIPELINING [RFC 1891] DSN [RFC 2554] AUTH (SASL) [RFC 2487] STARTTLS [RFC 1870] SIZE [RFC 1985] ETRN [RFC 1652] 8BITMIME [RFC 2852] DELIVERBY Supports is planned for the following SMTP extensions. As new SMTP extensions are defined, they will be implemented if they are relevant for use in programs that submit mail. [RFC 3030] CHUNKING [RFC 3030] BINARYMIME Please note that certain of the SMTP extensions are processed internally to libESMTP and do not require corresponding API functions. The libESMTP API is intended to be a relatively small and lightweight interface to the SMTP protocol and its extensions. However, given the number of API functions in libESMTP, this assertion is questionable. In mitigation, many of these are necessary because the internal structures are opaque to the application and most of them are used to define the messages and recipients to be transferred to the SMTP server during the protocol session. Similarly a significant number of functions are used to query the status of the transfer after the event. The entire SMTP protocol session is performed by only one function call. smtp_message_t smtp_add_message (smtp_session_t session); smtp_recipient_t smtp_add_recipient (smtp_message_t message, const char *mailbox); int smtp_auth_set_context (smtp_session_t session, auth_context_t context); smtp_session_t smtp_create_session (void); int smtp_destroy_session (smtp_session_t session); int smtp_dsn_set_envid (smtp_message_t message, const char *envid); int smtp_dsn_set_notify (smtp_recipient_t recipient, enum notify_flags flags); int smtp_dsn_set_orcpt (smtp_recipient_t recipient, const char *address_type, const char *address); int smtp_dsn_set_ret (smtp_message_t message, enum ret_flags flags); int smtp_enumerate_messages (smtp_session_t session, smtp_enumerate_messagecb_t cb, void *arg); int smtp_enumerate_recipients (smtp_message_t message, smtp_enumerate_recipientcb_t cb, void *arg); int smtp_errno (void); smtp_etrn_node_t smtp_etrn_add_node (smtp_session_t session, int option, const char *node); int smtp_etrn_enumerate_nodes (smtp_session_t session, smtp_etrn_enumerate_nodecb_t cb, void *arg); void *smtp_etrn_get_application_data (smtp_etrn_node_t node); const smtp_status_t *smtp_etrn_node_status (smtp_etrn_node_t node); void *smtp_etrn_set_application_data (smtp_etrn_node_t node, void *data); void *smtp_get_application_data (smtp_session_t session); void *smtp_message_get_application_data (smtp_message_t message); int smtp_message_reset_status (smtp_message_t recipient); void *smtp_message_set_application_data (smtp_message_t message, void *data); const smtp_status_t *smtp_message_transfer_status (smtp_message_t message); int smtp_recipient_check_complete (smtp_recipient_t recipient); void *smtp_recipient_get_application_data (smtp_recipient_t recipient); int smtp_recipient_reset_status (smtp_recipient_t recipient); void *smtp_recipient_set_application_data (smtp_recipient_t recipient, void *data); const smtp_status_t *smtp_recipient_status (smtp_recipient_t recipient); const smtp_status_t *smtp_reverse_path_status (smtp_message_t message); void *smtp_set_application_data (smtp_session_t session, void *data); int smtp_set_eventcb (smtp_session_t session, smtp_eventcb_t cb, void *arg); int smtp_set_header (smtp_message_t message, const char *header, ...); int smtp_set_header_option (smtp_message_t message, const char *header, enum header_option option, ...); int smtp_set_hostname (smtp_session_t session, const char *hostname); int smtp_set_messagecb (smtp_message_t message, smtp_messagecb_t cb, void *arg); int smtp_set_monitorcb (smtp_session_t session, smtp_monitorcb_t cb, void *arg, int headers); int smtp_set_resent_headers (smtp_message_t message, int onoff); int smtp_set_reverse_path (smtp_message_t message, const char *mailbox); int smtp_set_server (smtp_session_t session, const char *hostport); int smtp_size_set_estimate (smtp_message_t message, unsigned long size); int smtp_start_session (smtp_session_t session); int smtp_starttls_enable (smtp_session_t session, int how); int smtp_starttls_set_ctx (smtp_session_t session, SSL_CTX *ctx); char *smtp_strerror (int error, char buf[], size_t buflen); typedef void (*smtp_enumerate_messagecb_t) (smtp_message_t message, void *arg); typedef void (*smtp_enumerate_recipientcb_t) (smtp_recipient_t recipient, const char *mailbox, void *arg); typedef void (*smtp_etrn_enumerate_nodecb_t) (smtp_etrn_node_t node, int option, const char *domain, void *arg) typedef struct smtp_etrn_node *smtp_etrn_node_t; typedef void (*smtp_eventcb_t) (smtp_session_t session, smtp_message_t message, smtp_recipient_t recipient, int event_no, void *arg); typedef char *(*smtp_messagecb_t) (char **buf, int *len, void *arg); typedef struct smtp_message *smtp_message_t; typedef void (*smtp_monitorcb_t) (const char *buf, int buflen, int writing, void *arg); typedef struct smtp_recipient *smtp_recipient_t; typedef struct smtp_session *smtp_session_t; typedef struct smtp_status smtp_status_t; enum notify_flags; enum ret_flags; enum header_option; To use the libESMTP API, you must include libesmtp.h in all source files calling the API functions. Internally libESMTP creates and maintains three types of structures to build and track the state of an SMTP protocol session. Pointers to these structures are passed back to the application by the API and must be supplied in various other API calls. All structures and pointers maintained by libESMTP are opaque, that is, the internal detail of libESMTP structures is not made available to the application. The pointers 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; 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 Create a descriptor which maintains internal state for the SMTP session. The descriptor for the SMTP session or NULL on failure. smtp_add_message add a message to an SMTP session smtp_message_t smtp_add_message smtp_session_t session Add a message to the list of messages to be transferred to the remote MTA during an SMTP session. The descriptor for the message state, or NULL on failure. 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 Call the callback function once for each message in an smtp session. Zero on failure, non-zero on success. smtp_set_hostname set the name of the localhost int smtp_set_hostname smtp_session_t session const char *hostname Set the name of the localhost. If one is not specified, the local host name will be determined using uname. Zero on failure, non-zero on success. 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. Zero on failure, non-zero on success. The default port number is set to 587 since this is the port that should be used for mail submission, see RFC 2476. 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 2821. If a null reverse path is required, specify mailbox as NULL or "". If the value is a non-empty string and neither the message contains a From: header nor a From: is specified using smtp_set_header, the reverse path mailbox address specified with this API will be used to generate one. 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. Zero on failure, non-zero on success. Not calling this API has the same effect as specifing mailbox as NULL. 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 2821. If neither the message contains a To: header nor a To: is specified using smtp_set_header, a To: 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. The descriptor for the recipient state or NULL for failure. The envelope recipient need not be related to the To/Cc/Bcc recipients, for example, when a mail is resent to the recipients of a mailing list or as a result of alias expansion. 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 Call the callback function once for each recipient in the SMTP message. Zero on failure, non-zero on success. smtp_set_header set an RFC 2822 message header int smtp_set_header smtp_message_t message const char *header ... Set an RFC 2822 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. Zero on failure, non-zero on success. This section lists the additional function arguments for individual RFC 2822 headers. default const char *value Headers not specifically known to libESMTP are treated as simple string values. Date: 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 2822 when the value is required. The Date: header is automatically generated if one is not supplied either in the message or via the API. Message-Id: 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. From: Disposition-Notification-To: 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 2822, 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. To: Cc: Bcc: Reply-To: 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 2822, 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, in the words of RFC 2045, MIME (RFC 2045 - RFC 2049) is "orthogonal" to RFC 2822 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 2822 message header option. Hdr_OVERRIDE 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. Hdr_PROHIBIT 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 2822, such as Message-Id:. Setting Hdr_PROHIBIT ensures the transmitted message does not contain the named header. If the header is REQUIRED by RFC 2822, the API will fail. Zero on failure, non-zero on success. smtp_set_resent_headers smtp_set_resent_headers int smtp_set_resent_headers smtp_message_t message int onoff Request special processing of headers which have a Resent- variation. This option is used when resending messages as described in RFC 2822. Zero on failure, non-zero on success. 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 2822 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. Zero on failure, non-zero on success. 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, /* Protocol extension progress */ SMTP_EV_ETRNSTATUS = 1000, /* Required extensions */ SMTP_EV_EXTNA_DSN = 2000, SMTP_EV_EXTNA_8BITMIME, SMTP_EV_EXTNA_STARTTLS, SMTP_EV_EXTNA_ETRN, /* Extensions specific events */ SMTP_EV_DELIVERBY_EXPIRED = 3000, /* STARTTLS */ SMTP_EV_WEAK_CIPHER = 3100, SMTP_EV_STARTTLS_OK, SMTP_EV_INVALID_PEER_CERTIFICATE, SMTP_EV_NO_PEER_CERTIFICATE, SMTP_EV_WRONG_PEER_CERTIFICATE }; Set a callback function to process protocol events during the SMTP session with the server. The callback function is called when something significant happens, such as when server, message or recipient status codes are notified. Zero on failure, non-zero on success. 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. Zero on failure, non-zero on success. 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 These functions associate application defined data with each of the opaque structures. The set variants of the functions set a new value for the application data and return the old value in their respective structures. The get variants return the current value of the application data. 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 2822 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 Deallocate all resources associated with the SMTP session. smtp_version retrieve libESMTP version information int smtp_version void *buf size_t len int what Retrieve version information for the libESMTP in use. Zero on failure, non-zero on success. smtp_errno get error code for most recent API call int smtp_errno Retrieve the error code for the most recently failed API in the calling thread. libESMTP error code. #define SMTP_ERR_NOTHING_TO_DO 2 #define SMTP_ERR_DROPPED_CONNECTION 3 #define SMTP_ERR_INVALID_RESPONSE_SYNTAX 4 #define SMTP_ERR_STATUS_MISMATCH 5 #define SMTP_ERR_INVALID_RESPONSE_STATUS 6 #define SMTP_ERR_INVAL 7 #define SMTP_ERR_EXTENSION_NOT_AVAILABLE 8 /* libESMTP versions of some getaddrinfo error numbers */ #define SMTP_ERR_EAI_ADDRFAMILY 9 #define SMTP_ERR_EAI_NODATA 10 #define SMTP_ERR_EAI_FAIL 11 #define SMTP_ERR_EAI_AGAIN 12 #define SMTP_ERR_EAI_MEMORY 13 #define SMTP_ERR_EAI_FAMILY 14 #define SMTP_ERR_EAI_BADFLAGS 15 #define SMTP_ERR_EAI_NONAME 16 #define SMTP_ERR_EAI_SERVICE 17 #define SMTP_ERR_EAI_SOCKTYPE 18 SMTP_ERR_INVAL means that an API was called with invalid arguments. smtp_strerror convert error code to English text const char *smtp_strerror int error char buf[] size_t buflen Translate a libESMTP error number to a string suitable for use in an application error message. The resuting string is copied into buf. A pointer to the buf on success or NULL on failure. 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. NULL if no status information is available, otherwise a pointer to the status information. The pointer remains valid until the next call to libESMTP in the same thread. smtp_reverse_path_status const smtp_status_t *smtp_reverse_path_status smtp_message_t message Retrieve the reverse path 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. NULL if no status information is available, otherwise a pointer to the status information. The pointer remains valid until the next call to libESMTP in the same thread. smtp_message_reset_status smtp_message_reset_status int smtp_message_reset_status smtp_message_t recipient Reset the message status to the state it would have before smtp_start_session is called for the first time on the containing session. This may be used to force libESMTP to resend certain messages. Zero on failure, non-zero on success. 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. NULL if no status information is available, otherwise a pointer to the status information. The pointer remains valid until the next call to libESMTP in the same thread. smtp_recipient_check_complete smtp_recipient_check_complete int smtp_recipient_check_complete smtp_recipient_t recipient Check whether processing is complete dor the specified recipient of the message. Processing is considered complete when an MTA has assumed responsibility for delivering the message, or if it has indicated a permanent failure. Zero if processing is not complete, non-zero otherwise. smtp_recipient_reset_status smtp_recipient_reset_status int smtp_recipient_reset_status smtp_recipient_t recipient Reset the recipient status to the state it would have before smtp_start_session is called for the first time on the containing session. This is used to force the libESMTP to resend previously successful recipients. Zero on failure, non-zero on success. The following APIs relate to SMTP extensions. Note that not all supported extensions require corresponding API functions. smtp_dsn_set_ret 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 }; Instruct the reporting MTA whether to include the full content of the original message in the Delivery Status Notification, or just the headers. Non zero on success, zero on failure. smtp_dsn_set_envid smtp_dsn_set_envid int smtp_dsn_set_envid smtp_message_t message const char *envid Set the envelope identifier. This value is returned in the DSN and may be used by the MUA to associate the DSN with the message that caused it to be generated. Non zero on success, zero on failure. smtp_dsn_set_notify smtp_dsn_set_notify int smtp_dsn_set_notify smtp_recipient_t recipient enum notify_flags flags enum notify_flags { Notify_NOTSET, Notify_NEVER = -1, Notify_SUCCESS = 1, Notify_FAILURE = 2, Notify_DELAY = 4 }; Set the DSN notify options. Flags may be Notify_NOTSET or Notify_NEVER or any combination of Notify_SUCCESS, Notify_FAILURE and Notify_DELAY. Non zero on success, zero on failure. smtp_dsn_set_orcpt 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. Non zero on success, zero on failure. smtp_size_set_estimate smtp_size_set_estimate int smtp_size_set_estimate smtp_message_t message unsigned long size Used by the application to supply an estimate of the size of the message to be transferred. Non zero on success, zero on failure. smtp_8bitmime_set_body 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 2822 (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. Non zero on success, zero on failure. 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 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 Add an ETRN node to the SMTP session. The descriptor for the ETRN node, or NULL on failure. smtp_etrn_enumerate_nodes 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 Call the callback function once for each etrn node in the smtp session. Zero on failure, non-zero on success. smtp_etrn_node_status smtp_etrn_node_status const smtp_status_t *smtp_etrn_node_status smtp_etrn_node_t node Retrieve the ETRN node 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. NULL if no status information is available, otherwise a pointer to the status information. The pointer remains valid until the next call to libESMTP in the same thread. smtp_etrn_set_application_data 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 These functions associate application defined data with the opaque ETRN structure. The set variant sets a new value for the application data and returns the old value for the application data. The get variant returns the current value of the application data. smtp_auth_set_context 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 2222) 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. Non zero on success, zero on failure. 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 smtp_starttls_enable enum starttls_option { Starttls_DISABLED, Starttls_ENABLED, Starttls_REQUIRED }; int smtp_starttls_enable smtp_session_t session enum starttls_option how Enable the SMTP STARTTLS verb if how is not Starttls_DISABLED. If set to Starttls_REQUIRED the protocol will quit rather than transferring any messages if the STARTTLS extension is not available. Non zero on success, zero on failure. smtp_starttls_set_ctx smtp_starttls_set_ctx #include <openssl/ssl.h> #include <libesmtp.h> int smtp_starttls_set_ctx smtp_session_t session SSL_CTX *ctx Use an SSL_CTX created by the application. The SSL_CTX must be created by the application which is assumed to have initialised the OpenSSL library. If not used, OpenSSL is automatically initialised before calling any of the OpenSSL API functions. Non zero on success, zero on failure.