libESMTP API Reference

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


Caveat Programmer

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.

Introduction

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.

SMTP Extensions

libESMTP supports the following SMTP extensions. Those extensions which are useful only in Message Transport Agents (MTA) will not be implemented in libESMTP.

  • [RFC 3463, RFC 2034] ENHANCEDSTATUSCODES
  • [RFC 2920] PIPELINING
  • [RFC 3461] DSN
  • [RFC 4954] AUTH (SASL)
  • [RFC 3207] STARTTLS
  • [RFC 1870] SIZE
  • [RFC 3030] CHUNKING
  • [RFC 3030] BINARYMIME
  • [RFC 6152] 8BITMIME
  • [RFC 2852] DELIVERBY
  • [RFC 1985] ETRN
  • [sendmail] XUSR
  • [exchange] XEXCH50

Please note that certain SMTP extensions are processed internally to libESMTP and do not require corresponding API functions.

Reference

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.

Opaque Pointers

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;
	

Thread Safety

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.

Signal Handling

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

smtp_create_session — create SMTP session descriptor

Synopsis

smtp_session_t smtp_create_session( void);  
 

Description

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

Return Value

The descriptor for the SMTP session or NULL on failure.

smtp_add_message

smtp_add_message — add a message to an SMTP session

Synopsis

smtp_message_t smtp_add_message( smtp_session_t session);
 

Description

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

Return Value

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

smtp_enumerate_messages

smtp_enumerate_messages — enumerate messages in an SMTP session

Synopsis

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);
 

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 Value

Zero on failure, non-zero on success.

smtp_set_hostname

smtp_set_hostname — set the name of the localhost

Synopsis

int smtp_set_hostname( smtp_session_t session,
  const char *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 Value

Zero on failure, non-zero on success.

smtp_set_server

smtp_set_server — set the hostname of the message submission server

Synopsis

smtp_set_server( smtp_session_t session,
  const char *hostport);
 

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 Value

Zero on failure, non-zero on success.

Notes

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

smtp_set_reverse_path — set the reverse path mailbox

Synopsis

smtp_set_reverse_path( smtp_message_t message,
  const char *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 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.

Return Value

Zero on failure, non-zero on success.

Notes

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

smtp_add_recipient

smtp_add_recipient — add a recipient to a message

Synopsis

smtp_recipient_t smtp_add_recipient( smtp_message_t message,
  const char *mailbox);
 

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

Return Value

The descriptor for the recipient state or NULL for failure.

Notes

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

smtp_enumerate_recipients — enumerate message recipients

Synopsis

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);
 

Description

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

Return Value

Zero on failure, non-zero on success.

smtp_set_header

smtp_set_header — set an RFC 5322 message header

Synopsis

int smtp_set_header( smtp_message_t message,
  const char *header,
  ...);
 

Description

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.

Return Value

Zero on failure, non-zero on success.

Function Arguments

This section lists the additional function arguments for individual RFC 5322 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 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.

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 5322, for example username@example.org.

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:, Sender:
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 username@example.org. 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.

Notes

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

smtp_set_header_option — set options for message header processing

Synopsis

int smtp_set_header_option( smtp_message_t message,
  const char *header,
  enum header_option option,
  ...);
 

Description

enum header_option
  {
    Hdr_OVERRIDE,
    Hdr_PROHIBIT
  };
      

Set an RFC 5322 message header option.

Header Options

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

Return Value

Zero on failure, non-zero on success.

smtp_set_resent_headers

smtp_set_resent_headers

Synopsis

int smtp_set_resent_headers( smtp_message_t message,
  int onoff);
 

Description

Request special processing of headers which have a Resent- variation. This option is used when resending messages as described in RFC 5322.

Return Value

Zero on failure, non-zero on success.

Warning

Currently not implemented

smtp_set_timeout

smtp_set_timeout

Synopsis

long smtp_set_timeout( smtp_session_t session,
  int which,
  long value);
 

Description

Return Value

Non zero on success, zero on failure.

smtp_option_require_all_recipients

smtp_option_require_all_recipients

Synopsis

      
int smtp_option_require_all_recipients( smtp_session_t session,
  int state);
 

Description

Return Value

Non zero on success, zero on failure.

smtp_set_messagecb

smtp_set_messagecb — set callback for reading the message from an application

Synopsis

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);
 

Description

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.

Return Value

Zero on failure, non-zero on success.

smtp_set_message_fp

smtp_set_message_fp

Synopsis

      
int smtp_set_message_fp( smtp_message_t message,
  FILE *fp);
 

Description

Return Value

Non zero on success, zero on failure.

smtp_set_message_str

smtp_set_message_str

Synopsis

int smtp_set_message_str( smtp_message_t message,
  const char *string);
 

Description

Return Value

Non zero on success, zero on failure.

smtp_set_eventcb

smtp_set_eventcb — set callback for reporting events to the applciation

Synopsis

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
  };
      

Description

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.

Return Value

Zero on failure, non-zero on success.

smtp_set_monitorcb

smtp_set_monitorcb — set callback for tracing the SMTP protocol session

Synopsis

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
      

Description

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.

Return Value

Zero on failure, non-zero on success.

smtp_set_application_data

smtp_set_application_data — attach application data to libESMTP structures

Synopsis

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);
 

Description

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.

Return Value

smtp_start_session

smtp_start_session — run an SMTP protocol session

Synopsis

int smtp_start_session( smtp_session_t session);
 

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 Value

smtp_destroy_session

smtp_destroy_session — release all resources associated with an SMTP session

Synopsis

int smtp_destroy_session( smtp_session_t session);
 

Description

Deallocate all resources associated with the SMTP session.

Return Value

smtp_version

smtp_version — retrieve libESMTP version information

Synopsis

int smtp_version( void *buf,
  size_t len,
  int what);
 

Description

Retrieve version information for the libESMTP in use.

Return Value

Zero on failure, non-zero on success.

smtp_errno

smtp_errno — get error code for most recent API call

Synopsis

int smtp_errno( );
 

Description

Retrieve the error code for the most recently failed API in the calling thread.

Return Value

libESMTP error code.

Error Codes

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.

smtp_strerror

smtp_strerror — convert error code to English text

Synopsis

const char *smtp_strerror( int error,
  char buf[],
  size_t buflen);
 

Description

Translate a libESMTP error number to a string suitable for use in an application error message. The resuting string is copied into buf.

Return Value

A pointer to the buf on success or NULL on failure.

SMTP Status codes

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

smtp_message_transfer_status

Synopsis

const smtp_status_t *smtp_message_transfer_status( smtp_message_t 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 Value

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

smtp_reverse_path_status

Synopsis

const smtp_status_t *smtp_reverse_path_status( smtp_message_t 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 Value

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

Synopsis

int smtp_message_reset_status( smtp_message_t recipient);
 

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 Value

Zero on failure, non-zero on success.

smtp_recipient_status

smtp_recipient_status

Synopsis

const smtp_status_t *smtp_recipient_status( smtp_recipient_t 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 Value

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

Synopsis

int smtp_recipient_check_complete( smtp_recipient_t 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 Value

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

smtp_recipient_reset_status

smtp_recipient_reset_status

Synopsis

int smtp_recipient_reset_status( smtp_recipient_t 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 Value

Zero on failure, non-zero on success.

SMTP Extensions

The following APIs relate to SMTP extensions. Note that not all supported extensions require corresponding API functions.

RFC 3461. Delivery Status Notification (DSN)

smtp_dsn_set_ret

smtp_dsn_set_ret

Synopsis

int smtp_dsn_set_ret( smtp_message_t message,
  enum ret_flags flags);
 
enum ret_flags { Ret_NOTSET, Ret_FULL, Ret_HDRS };
      

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 Value

Non zero on success, zero on failure.

smtp_dsn_set_envid

smtp_dsn_set_envid

Synopsis

int smtp_dsn_set_envid( smtp_message_t message,
  const char *envid);
 

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 Value

Non zero on success, zero on failure.

smtp_dsn_set_notify

smtp_dsn_set_notify

Synopsis

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
  };
      

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 Value

Non zero on success, zero on failure.

smtp_dsn_set_orcpt

smtp_dsn_set_orcpt

Synopsis

int smtp_dsn_set_orcpt( smtp_recipient_t recipient,
  const char *address_type,
  const char *address);
 

Description

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.

Return Value

Non zero on success, zero on failure.

RFC 1870. SMTP Size Extension.

smtp_size_set_estimate

smtp_size_set_estimate

Synopsis

int smtp_size_set_estimate( smtp_message_t message,
  unsigned long size);
 

Description

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

Return Value

Non zero on success, zero on failure.

RFC 6152. SMTP 8bit-MIME Transport Extension

smtp_8bitmime_set_body

smtp_8bitmime_set_body

Synopsis

int smtp_8bitmime_set_body( smtp_message_t message,
  enum e8bitmime_body body);
 
enum e8bitmime_body
  {
    E8bitmime_NOTSET,
    E8bitmime_7BIT,
    E8bitmime_8BITMIME
  };
      

Description

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.

Return Value

Non zero on success, zero on failure.

RFC 1985. Remote Message Queue Starting (ETRN)

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

Synopsis

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);
 

Description

Add an ETRN node to the SMTP session.

Return Value

The descriptor for the ETRN node, or NULL on failure.

smtp_etrn_enumerate_nodes

smtp_etrn_enumerate_nodes

Synopsis

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);
 

Description

Call the callback function once for each etrn node in the smtp session.

Return Value

Zero on failure, non-zero on success.

smtp_etrn_node_status

smtp_etrn_node_status

Synopsis

const smtp_status_t *smtp_etrn_node_status( smtp_etrn_node_t node);
 

Description

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.

Return Value

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

Synopsis

void *smtp_etrn_set_application_data( smtp_etrn_node_t node,
  void *arg);
 
void *smtp_etrn_get_application_data( smtp_etrn_node_t node);
 

Description

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.

Return Value

RFC 4954. SMTP Auth Extension

smtp_auth_set_context

smtp_auth_set_context

Synopsis

#include <auth-client.h>
#include <libesmtp.h>
      
int smtp_auth_set_context( smtp_session_t session,
  auth_context_t context);
 

Description

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.

Authentication Contexts

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.

Return Value

Non zero on success, zero on failure.

RFC 2487. SMTP StartTLS Extension

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

Synopsis

enum starttls_option
  {
    Starttls_DISABLED,
    Starttls_ENABLED,
    Starttls_REQUIRED
  };
      
int smtp_starttls_enable( smtp_session_t session,
  enum starttls_option how);
 

Description

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.

Return Value

Non zero on success, zero on failure.

smtp_starttls_set_ctx

smtp_starttls_set_ctx

Synopsis

#include <openssl/ssl.h>
#include <libesmtp.h>
      
int smtp_starttls_set_ctx( smtp_session_t session,
  SSL_CTX *ctx);
 

Description

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.

Return Value

Non zero on success, zero on failure.

smtp_starttls_set_password_cb

smtp_starttls_set_password_cb — set password callback function for OpenSSL

Synopsis

typedef int (*smtp_starttls_passwordcb_t) (char *buf, int buflen,
                                           int rwflag, void *arg);
      
int smtp_starttls_set_password_cb( smtp_session_t session,
  void *arg);
 

Description

Return Value

Non zero on success, zero on failure.

RFC 2852. SMTP Deliver By Extension

smtp_deliverby_set_mode

smtp_deliverby_set_mode

Synopsis

      
int smtp_deliverby_set_mode( smtp_message_t message,
  long time,
  enum by_mode mode,
  int trace);
 

Description

Return Value

Non zero on success, zero on failure.