libESMTP API Reference

Core API¶

The following describes the libESMTP core API which implements the functionality covered in RFC 5321 and RFC 5322.

smtp_session_t smtp_create_session(void)¶: Create a libESMTP session.

Parameters

void: no arguments

Description

Create a descriptor which maintains internal state for the SMTP session.

Return

A new SMTP session or NULL on failure.

int smtp_set_server(smtp_session_t session, const char *hostport)¶: Set host and service for submission MTA.

Parameters

smtp_session_t session: The session.
const char *hostport: Hostname and port (service) for the SMTP server.

Description

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.

Return

Zero on failure, non-zero on success.

const char *smtp_get_server_name(smtp_session_t session)¶: get submission MTA canonic hostname.

Parameters

smtp_session_t session: The session.

Description

Get the canonic host name for the submission MTA. This is only valid after smtp_start_session() has been called, for example in the event callback after a connection has been established. If the canonic name is not available the host name set in smtp_set_server() is returned instead.

Return

MTA hostname or NULL.

int smtp_set_hostname(smtp_session_t session, const char *hostname)¶: Set the local host name.

Parameters

smtp_session_t session: The session.
const char *hostname: The local hostname.

Description

Set the name of the localhost. If hostname is NULL, the local host name will be determined using uname(). If the system does not provide uname() or equivalent, the hostname parameter may not be NULL.

Return

Zero on failure, non-zero on success.

smtp_message_t smtp_add_message(smtp_session_t session)¶: Add a message to the session.

Parameters

smtp_session_t session: The session.

Description

Add a message to the list of messages to be transferred to the remote MTA during an SMTP session.

Return

The descriptor for the message state, or NULL on failure.

int smtp_enumerate_messages(smtp_session_t session, smtp_enumerate_messagecb_t cb, void *arg)¶: Call function for each message in session.

Parameters

smtp_session_t session: The session.
smtp_enumerate_messagecb_t cb: callback function
void *arg: user data passed to the callback

Description

Call the callback function once for each message in an smtp session. The arg parameter is passed back to the application via the callback’s parameter of the same name.

Return

Zero on failure, non-zero on success.

const smtp_status_t *smtp_message_transfer_status(smtp_message_t message)¶: Retrieve message status.

Parameters

smtp_message_t message: The message.

Description

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.

Return

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.

int smtp_set_reverse_path(smtp_message_t message, const char *mailbox)¶: Set reverse path mailbox.

Parameters

smtp_message_t message: The message.
const char *mailbox: Reverse path mailbox.

Description

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

Not calling this API has the same effect as specifing mailbox as NULL.

Return

Zero on failure, non-zero on success.

const smtp_status_t *smtp_reverse_path_status(smtp_message_t message)¶: Get the reverse path status.

Parameters

smtp_message_t message: The message.

Description

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.

Return

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.

int smtp_message_reset_status(smtp_message_t message)¶: Reset message status.

Parameters

smtp_message_t message: The message.

Description

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.

Return

Zero on failure, non-zero on success.

smtp_recipient_t smtp_add_recipient(smtp_message_t message, const char *mailbox)¶: Add a message recipient.

Parameters

smtp_message_t message: The message.
const char *mailbox: Recipient mailbox address.

Description

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 recommended that the message supplies To:, Cc: and Bcc: headers or that the libESMTP header APIs are used to create them.

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.

Return

The descriptor for the recipient state or NULL for failure.

int smtp_enumerate_recipients(smtp_message_t message, smtp_enumerate_recipientcb_t cb, void *arg)¶: Call a function for each recipient.

Parameters

smtp_message_t message: The message.
smtp_enumerate_recipientcb_t cb: Callback function to process recipient.
void *arg: User data passed to the callback.

Description

Call the callback function once for each recipient in the SMTP message.

Return

Zero on failure, non-zero on success.

const smtp_status_t *smtp_recipient_status(smtp_recipient_t recipient)¶: Get the recipient status.

Parameters

smtp_recipient_t recipient: The recipient.

Description

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.

Return

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.

int smtp_recipient_check_complete(smtp_recipient_t recipient)¶: Check if recipient processing is completed.

Parameters

smtp_recipient_t recipient: The recipient.

Description

Check whether processing is complete for 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.

Return

Zero if processing is not complete, non-zero otherwise.

int smtp_recipient_reset_status(smtp_recipient_t recipient)¶: Reset recipient status.

Parameters

smtp_recipient_t recipient: The recipient.

Description

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.

Return

Zero on failure, non-zero on success.

RFC 3461.

Delivery Status Notification (DSN)¶

The following APIs implement Delivery Status Notification (DSN) as described in RFC 3461.

int smtp_dsn_set_ret(smtp_message_t message, enum ret_flags flags)¶: Set DSN return flags.

Parameters

smtp_message_t message: The message.
enum ret_flags flags: an enum ret_flags

Description

Instruct the reporting MTA whether to include the full content of the original message in the Delivery Status Notification, or just the headers.

Return

Zero on failure, non-zero on success.

int smtp_dsn_set_envid(smtp_message_t message, const char *envid)¶: Set the envelope identifier.

Parameters

smtp_message_t message: The message.
const char *envid: Envelope idientifier.

Description

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.

Return

Zero on failure, non-zero on success.

int smtp_dsn_set_notify(smtp_recipient_t recipient, enum notify_flags flags)¶: Set the DSN notify flags.

Parameters

smtp_recipient_t recipient: The recipient.
enum notify_flags flags: An enum notify_flags

Description

Set the DSN notify options. Flags may be Notify_NOTSET or Notify_NEVER or the bitwise OR of any combination of Notify_SUCCESS, Notify_FAILURE and Notify_DELAY.

Return

Zero on failure, non-zero on success.

int smtp_dsn_set_orcpt(smtp_recipient_t recipient, const char *address_type, const char *address)¶: Set the DSN ORCPT option.

Parameters

smtp_recipient_t recipient: The recipient.
const char *address_type: String specifying the address type.
const char *address: String specifying the original recipient address.

Description

Set the DSN ORCPT option. This DSN option is used only 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.

Return

Non zero on success, zero on failure.

RFC 1870

Size Extention¶

The following APIs implement the SMTP size extention as described in RFC 1870.

int smtp_size_set_estimate(smtp_message_t message, unsigned long size)¶: Set the message size estimate.

Parameters

smtp_message_t message: The message.
unsigned long size: The size estimate

Description

Used by the application to supply an estimate of the size of the message to be transferred.

Return

Non zero on success, zero on failure.

RFC 6152.

8bit-MIME Transport Extension¶

The 8-bit MIME extension described in RFC 6152 allows an SMTP client to declare the message body is either in strict conformance with RFC 5322 or that it is a MIME document where some or all of the MIME parts use 8-bit encoding.

int smtp_8bitmime_set_body(smtp_message_t message, enum e8bitmime_body body)¶: Set message body options.

Parameters

smtp_message_t message: The message.
enum e8bitmime_body body: Constant from enum e8bitmime_body.

Description

Declare the message body conformance. If the body type is not E8bitmime_NOTSET, libESMTP will use the event callback to notify the application if the MTA does not support the 8BITMIME extension.

Return

Non zero on success, zero on failure.

RFC 2852.

Deliver By Extension¶

int smtp_deliverby_set_mode(smtp_message_t message, long time, enum by_mode mode, int trace)¶: Set delivery tracing and conditions.

Parameters

smtp_message_t message: The message.
long time: Deliver by specified time.
enum by_mode mode: Delivery mode.
int trace: Trace mode.

Description

If time is before the earliest time the server can guarantee delivery, libESMTP will emit a SMTP_EV_DELIVERBY_EXPIRED event. The application may optionally adjust latest acceptable the delivery time, otherwise the MAIL command will be failed by the server.

Return

Non zero on success, zero on failure.

Callbacks

Callbacks¶

int smtp_set_messagecb(smtp_message_t message, smtp_messagecb_t cb, void *arg)¶: Set message reader.

Parameters

smtp_message_t message: The message.
smtp_messagecb_t cb: Callback function.
void *arg: application data (closure) passed to the callback.

Description

Set a callback function to read the message.

Return

Non zero on success, zero on failure.

int smtp_set_eventcb(smtp_session_t session, smtp_eventcb_t cb, void *arg)¶: Set event callback.

Parameters

smtp_session_t session: The session.
smtp_eventcb_t cb: Callback function.
void *arg: application data (closure) passed to the callback.

Description

Set callback to be called as protocol events occur.

Return

Non zero on success, zero on failure.

int smtp_set_monitorcb(smtp_session_t session, smtp_monitorcb_t cb, void *arg, int headers)¶: Set protocol monitor.

Parameters

smtp_session_t session: The session.
smtp_monitorcb_t cb: Callback function.
void *arg: application data (closure) passed to the callback.
int headers: non-zero to view headers.

Description

Set callback to be monitor the SMTP session. The monitor function is called to with the text of the protocol exchange and is flagged as being from the server or the client. Because the message body is potentially large it is excluded from the monitor. However, headers is non-zero the message headers are monitored.

Return

Non zero on success, zero on failure.

Protocol

SMTP Protocol¶

int smtp_start_session(smtp_session_t session)¶: Start an SMTP session.

Parameters

smtp_session_t session: The session to start.

Description

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.

Return

Zero on failure, non-zero on success.

Teardown

Tear Down Session¶

int smtp_destroy_session(smtp_session_t session)¶: Destroy a libESMTP session.

Parameters

smtp_session_t session: The session.

Description

Deallocate all resources associated with the SMTP session.

If application data has been set on any of the libESMTP structures, the associated destroy callback will be called with the application data as an argument.

If the deprecated legacy APIs are used to set application data or a destroy callback is not provided, the application must explicitly enumerate all messages and their recipients, and retrieve the data to be freed.

Return

always returns 1

Data

Application Data¶

Applications may attach arbitrary data to any of the libESMTP structures. The _release() variants of the APIs are preferred to the legacy versions as these will call a destroy callback when the smtp_session_t structure is destroyed, helping to avoid memory leaks that might have occurred using the deprecated APIs.

void *smtp_set_application_data(smtp_session_t session, void *data)¶: Associate data with a session.

Parameters

smtp_session_t session: The session.
void *data: Application data

Description

Associate application data with the session.

Only available when LIBESMTP_ENABLE_DEPRECATED_SYMBOLS is defined. Use smtp_set_application_data_release() instead.

Return

Previously set application data or NULL

void smtp_set_application_data_release(smtp_session_t session, void *data, void (*release)(void*))¶: Associate data with a session.

Parameters

smtp_session_t session: The session.
void *data: Application data
void (*release) (void *): function to free/unref data.

Description

Associate application data with the session. If release is non-NULL it is called to free or unreference data when changed or the session is destroyed.

void *smtp_get_application_data(smtp_session_t session)¶: Get data from a session.

Parameters

smtp_session_t session: The session.

Description

Get application data from the session.

Return

Previously set application data or NULL

void *smtp_message_set_application_data(smtp_message_t message, void *data)¶: Associate data with a message.

Parameters

smtp_message_t message: The message.
void *data: Application data

Description

Associate application data with the message.

Only available when LIBESMTP_ENABLE_DEPRECATED_SYMBOLS is defined. Use smtp_message_set_application_data_release() instead.

Return

Previously set application data or NULL

void smtp_message_set_application_data_release(smtp_message_t message, void *data, void (*release)(void*))¶: Associate data with a message.

Parameters

smtp_message_t message: The message.
void *data: Application data
void (*release) (void *): function to free/unref data.

Description

Associate application data with the message. If release is non-NULL it is called to free or unreference data when changed or the message is destroyed.

void *smtp_message_get_application_data(smtp_message_t message)¶: Get data from a message.

Parameters

smtp_message_t message: The message.

Description

Get application data from the message.

Return

Previously set application data or NULL

void *smtp_recipient_set_application_data(smtp_recipient_t recipient, void *data)¶: Associate data with a recipient.

Parameters

smtp_recipient_t recipient: The recipient.
void *data: Application data

Description

Associate application data with the recipient.

Only available when LIBESMTP_ENABLE_DEPRECATED_SYMBOLS is defined. Use smtp_recipient_set_application_data_release() instead.

Return

Previously set application data or NULL

void smtp_recipient_set_application_data_release(smtp_recipient_t recipient, void *data, void (*release)(void*))¶: Associate data with a recipient.

Parameters

smtp_recipient_t recipient: The recipient.
void *data: Application data
void (*release) (void *): function to free/unref data.

Description

Associate application data with the recipient. If release is non-NULL it is called to free or unreference data when changed or the recipient is destroyed.

void *smtp_recipient_get_application_data(smtp_recipient_t recipient)¶: Get data from a recipient.

Parameters

smtp_recipient_t recipient: The recipient.

Description

Get application data from the recipient.

Return

Previously set application data or NULL

Miscellaneous

Miscellaneous APIs¶

int smtp_version(void *buf, size_t len, int what)¶: Identify libESMTP version.

Parameters

void *buf: Buffer to receive version string.
size_t len: Length of buffer.
int what: Which version information to be retrieved.

Description

Retrieve version information for the libESMTP in use. The version number depends on the what parameter.

Ver_VERSION – the libESMTP version is returned
Ver_SO_VERSION – the .so file version is returned
Ver_LT_VERSION – the libtool style API version is returned.

If the supplied buffer is too small to receive the version number, this function fails.

Return

Zero on failure, non-zero on success.

int smtp_option_require_all_recipients(smtp_session_t session, int state)¶: FAIL if server rejects any recipient.

Parameters

smtp_session_t session: The session.
int state: Boolean set non-zero to enable.

Description

Some applications can’t handle one recipient from many failing particularly well. If the require_all_recipients option is set, this will fail the entire transaction even if some of the recipients were accepted in the RCPT commands.

Return

Non zero on success, zero on failure.

long smtp_set_timeout(smtp_session_t session, int which, long value)¶: Set session timeouts.

Parameters

smtp_session_t session: The session.
int which: Which timeout to set. A constant from enum rfc2822_timeouts.
long value: duration of timeout in seconds.

Description

Set the protocol timeouts. which is a constant from enum rfc2822_timeouts specifying which timeout to set. The minimum values recommended in RFC 5322 are enforced unless which is bitwise-ORed with Timeout_OVERRIDE_RFC2822_MINIMUM. An absolute minumum timeout of one second is imposed.

Return

the actual timeout set or zero on error.