### Build and Install with Meson and Ninja

Source: https://libesmtp.github.io/download.html

Configure the build with Meson and then build and install using Ninja. The installer will prompt for a password, avoiding root-owned files in the build directory.

```bash
$ meson [options] --buildtype=release builddir
$ ninja -C builddir install

```

--------------------------------

### C API for SMTP Session Creation and Configuration

Source: https://libesmtp.github.io/critique.html

This C code demonstrates the basic setup of an SMTP session, including creating a session, setting the server, adding a message, setting the reverse path, adding a recipient, and starting the session.

```c
  smtp_session_t session;
  smtp_message_t message;
  smtp_recipient_t recipient;

  session = smtp_create_session ();
  smtp_set_server (session, "example.org:587");

  /* ... */

  message = smtp_add_message (session);
  smtp_set_reverse_path (message, "brian@example.org");
  recipient = smtp_add_recipient (message, "douglas@h2g2.info");

  /* ... */

  smtp_start_session (session);

```

--------------------------------

### Pythonic SMTP Session with File Input and Iteration

Source: https://libesmtp.github.io/critique.html

This Python example demonstrates a more Pythonic way to configure an SMTP session, including setting the server via a property, loading message content from a file, and iterating through messages and recipients.

```python
from libESMTP import Session

session = Session()
session.server = 'example.org:587'

# ...

message = session.add_message()
message.reverse_path = 'brian@example.org'
with open('message.txt','r') as filp:
    message.fromfile(filp)

recipient = message.add_recipient('douglas@h2g2.info')

# ...

session.start()

for message in session.messages():
    print('From:', message.reverse_path)
    for recipient in message.recipients():
        print('To:', recipient.mailbox, recipient.status)


```

--------------------------------

### no_client_certificate

Source: https://libesmtp.github.io/reference/tlsevents.html

Callback indicating that a private key could not be found for a client certificate. libESMTP will not proceed with the TLS setup.

```APIDOC
## no_client_certificate

### Description
Report that a private key could not be found for a certificate libESMTP has attempted to load when initialising an OpenSSL TLS context. By default libESMTP will not continue to set up the TLS connection. Note that this is different to not providing a client certificate at all.

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Method
Callback function

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - Equal to `SMTP_EV_NO_CLIENT_CERTIFICATE`
- **arg** (void *) - application data (closure) specified to smtp_set_eventcb().
- **ok** (int *) - Set zero to quit SMTP session, non-zero to continue.

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Pythonic SMTP Session Setup with libESMTP Bindings

Source: https://libesmtp.github.io/critique.html

This Python code shows a more object-oriented approach to setting up an SMTP session using hypothetical libESMTP bindings, mirroring the C API's functionality.

```python
from libESMTP import Session, Message, Recipient

session = Session()
session.set_server ('example.org:587')

# ...

message = Message(session)
message.set_reverse_path("brian@example.org")
recipient = Recipient(message, 'douglas@h2g2.info')

# ...

session.start()

```

--------------------------------

### Employer Copyright Disclaimer Example

Source: https://libesmtp.github.io/reference/licence.html

A sample copyright disclaimer for an employer to sign, releasing their interest in a library developed by an employee.

```text
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random
Hacker.

<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
```

--------------------------------

### Start SMTP Session

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Initiates an SMTP mail submission session. Connects to the server, constructs the SMTP envelope, and transfers messages. Headers are processed until CR-LF is encountered, after which the message content is copied verbatim. The connection is established and closed within this function call.

```c
int smtp_start_session(smtp_session_t session)
```

--------------------------------

### Get Application Data from ETRN Node

Source: https://libesmtp.github.io/reference/_kdoc/smtp-etrn.html

Retrieve application-specific data that was previously associated with an ETRN node.

```c
void *smtp_etrn_get_application_data(smtp_etrn_node_t node);
```

--------------------------------

### starttls_ok

Source: https://libesmtp.github.io/reference/tlsevents.html

Callback invoked upon successful TLS connection establishment. It provides details about the negotiated cipher and the OpenSSL context.

```APIDOC
## starttls_ok

### Description
Report a successful TLS connection and the cipher details. The OpenSSL context is passed so that the application may query further information.

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Method
Callback function

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - Equal to `SMTP_EV_STARTTLS_OK`
- **arg** (void *) - application data (closure) specified to smtp_set_eventcb().
- **ssl** (SSL *) - The OpenSSL TLS context.
- **cipher** (const char *) - Name of negotiated cipher.
- **bits** (int) - cipher key size in bits.

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Applying Licence Terms to New Libraries

Source: https://libesmtp.github.io/reference/licence.html

This is a template for applying the GNU Lesser General Public License to a new library. It includes copyright information, redistribution rights, and warranty disclaimers.

```text
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
USA
```

--------------------------------

### Enable STARTTLS Verb

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Enable the STARTTLS extension for the SMTP session. Setting `how` to `Starttls_REQUIRED` will cause the protocol to quit if STARTTLS is not available, ensuring message transfer only occurs over a secure connection.

```c
int smtp_starttls_enable(smtp_session_t session, enum starttls_option how);
```

--------------------------------

### Get libESMTP Error Number

Source: https://libesmtp.github.io/reference/_kdoc/errors.html

Retrieve the error code for the most recently failed API call within the current thread. This function takes no arguments.

```c
int error_code = smtp_errno();
```

--------------------------------

### Basic libESMTP Application Structure

Source: https://libesmtp.github.io/reference/programflow.html

This snippet demonstrates the fundamental steps for creating and managing an ESMTP session using libESMTP. It covers session creation, adding messages and recipients, setting callbacks, configuring TLS and server details, and session tear-down. Ensure you implement the `get_recipient`, `message_cb`, and `event_cb` functions.

```c
void
libesmtp_application ()
{
  /* Create the libESMTP session */
  session = smtp_create_session ();

  /* Add a message. */
  message = smtp_add_message (session);

  /* Add recipients to the message. */
  while ((address = get_recipient ()) != NULL)
    {
      recipient = smtp_add_recipient (message, address);

      /* set a recipient option, e.g. to request a DSN if anything fails */
      smtp_dsn_set_notify (recipient, Notify_DELAY | Notify_FAILURE);
    }

  /* A callback to read the message from the application is required */
  smtp_set_messagecb (message, message_cb, arg);

  /* Add a header in case the application does not supply one via the
     message callback */
  smtp_set_header (message, "To", "Joe Bloggs", "joe.bloggs@example.org");

  /* Use TLS to secure the session */
  smtp_starttls_enable (session, Starttls_REQUIRED);

  /* Set the submission host (aka smarthost) */
  smtp_set_server (session, "msa.example.org:587");

  /* set an event callback and start the session */
  smtp_set_eventcb (session, event_cb, NULL);
  smtp_start_session (session);

  /* tear down the session */
  smtp_destroy_session (session);
}

```

--------------------------------

### starttls_option

Source: https://libesmtp.github.io/reference/_kdoc/libesmtp.html

Enumeration for TLS mode options during STARTTLS negotiation.

```APIDOC
## starttls_option

### Description
TLS mode options

### Constants
- **Starttls_DISABLED** - Do not use TLS, even if offered by the MTA.
- **Starttls_ENABLED** - Use TLS if offered by the MTA.
- **Starttls_REQUIRED** - Exit session if TLS is not offered by the MTA.
```

--------------------------------

### smtp_etrn_add_node

Source: https://libesmtp.github.io/reference/_kdoc/smtp-etrn.html

Creates an ETRN node for a given SMTP session, option, and domain. This node represents a request to the remote MTA to start its delivery queue for the specified domain.

```APIDOC
## smtp_etrn_add_node

### Description
Add an ETRN node to the SMTP session.

### Parameters
- **session** (smtp_session_t) - The SMTP session.
- **option** (int) - The option character.
- **domain** (const char *) - Request mail for this domain.

### Return
An `typedef smtp_etrn_node_t` or `NULL` on failure.
```

--------------------------------

### Retrieve ETRN Node Status

Source: https://libesmtp.github.io/reference/_kdoc/smtp-etrn.html

Get the success or failure status of a previously created ETRN node. This includes SMTP status codes, enhanced status codes, and server-provided text.

```c
const smtp_status_t *smtp_etrn_node_status(smtp_etrn_node_t node);
```

--------------------------------

### auth_client_init

Source: https://libesmtp.github.io/reference/_kdoc/auth-client.html

Initializes the auth client. This function should be called before any other auth client APIs to perform necessary preparations.

```APIDOC
## auth_client_init

### Description
Perform any preparation necessary for the auth client modules.

### Parameters
`void` - no arguments

### Returns
`void`
```

--------------------------------

### Build with Clang Static Analyzer

Source: https://libesmtp.github.io/download.html

To use the clang static analyzer, set the SCANBUILD environment variable to the absolute path of the scan-build binary and then run Meson and Ninja.

```bash
SCANBUILD=`which scan-build-10` meson builddir [options]
ninja -C builddir scan-build

```

--------------------------------

### smtp_starttls_enable

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Enables the STARTTLS command for the SMTP session. The behavior can be configured to be required, in which case the session will terminate if STARTTLS is not available.

```APIDOC
## smtp_starttls_enable

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

### Parameters
#### Parameters
- **session** (smtp_session_t) - The session.
- **how** (enum starttls_option) - A `enum starttls_option`.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### smtp_starttls_set_ctx

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Allows an application to provide its own pre-configured OpenSSL SSL_CTX for the SMTP session. If not provided or set to NULL, libESMTP will initialize OpenSSL automatically.

```APIDOC
## smtp_starttls_set_ctx

### Description
Use an SSL_CTX created and initialised by the application. The SSL_CTX must be created by the application which is assumed to have also initialised the OpenSSL library.
If not used, or **ctx** is `NULL`, OpenSSL is automatically initialised before calling any of the OpenSSL API functions.

### Parameters
#### Parameters
- **session** (smtp_session_t) - The session.
- **ctx** (SSL_CTX *) - An SSL_CTX initialised by the application.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### Include libESMTP Headers

Source: https://libesmtp.github.io/reference/introduction.html

Include the necessary header files to use the libESMTP API. Ensure correct macro definitions if deprecated symbols are needed.

```c
#include <auth-client.h>
#include <libesmtp.h>

```

```c
#define LIBESMTP_ENABLE_DEPRECATED_SYMBOLS
#include <libesmtp.h>

```

--------------------------------

### smtp_set_server

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Sets the host and service (port) for the submission MTA. The format is 'host.example.org[:service]', defaulting to port 587 if not specified. Returns non-zero on success, zero on failure.

```APIDOC
## smtp_set_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.

### Method
`smtp_set_server(smtp_session_t session, const char *hostport)`

### Parameters
* **session** (`smtp_session_t`) - The session.
* **hostport** (`const char *`) - Hostname and port (service) for the SMTP server.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### smtp_starttls_passwordcb_t

Source: https://libesmtp.github.io/reference/_kdoc/libesmtp.html

Callback function signature for providing a password during STARTTLS. It mirrors the OpenSSL declaration.

```APIDOC
## smtp_starttls_passwordcb_t

### Description
The callback function declaration is cleverly chosen to be the same as the OpenSSL declaration.

### Syntax
`int smtp_starttls_passwordcb_t (char *buf, int buflen, int rwflag, void *arg)`

### Parameters
#### Path Parameters
- **buf** (char *) - Buffer to receive the password.
- **buflen** (int) - Length of the buffer.
- **rwflag** (int) - 0 for reading/decryption, 1 for writing/encryption.
- **arg** (void *) - User data passed to smtp_starttls_set_password_cb().

### Return
Actual length of password.
```

--------------------------------

### Set SSL Context for SMTP Session

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Provide a pre-initialized `SSL_CTX` for the SMTP session. The application is responsible for creating and initializing the `SSL_CTX` and the OpenSSL library. If `ctx` is NULL or this function is not used, OpenSSL is initialized automatically.

```c
int smtp_starttls_set_ctx(smtp_session_t session, SSL_CTX *ctx);
```

--------------------------------

### smtp_start_session

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Initiates an SMTP session to connect to a server, transfer messages, and construct the SMTP envelope. The connection is established and closed within this function call.

```APIDOC
## smtp_start_session

### Description
Start an SMTP session. 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.

### Parameters
#### Session
- **session** (smtp_session_t) - The session to start.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### unusable_client_certificate

Source: https://libesmtp.github.io/reference/tlsevents.html

Callback for file errors encountered while loading a client certificate. TLS connections will not be established until the error is resolved.

```APIDOC
## unusable_client_certificate

### Description
Report a file error when attempting to load a client certificate. libESMTP will not make TLS connections until the error is corrected.

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Method
Callback function

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - Equal to `SMTP_EV_UNUSABLE_CLIENT_CERTIFICATE`
- **arg** (void *) - application data (closure) specified to smtp_set_eventcb().
- **null** (void *) - always `NULL`

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Set DSN Return Flags

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Configure whether the full message content or just headers should be included in the Delivery Status Notification. Returns non-zero on success, zero on failure.

```c
int smtp_dsn_set_ret(smtp_message_t message, enum ret_flags flags);
```

--------------------------------

### Define CONFIG for Legacy Layout

Source: https://libesmtp.github.io/reference/certificates.html

This shell command defines the CONFIG variable for the deprecated libESMTP legacy file layout convention.

```shell
CONFIG=$HOME/.authenticate
```

--------------------------------

### Clone LibESMTP Repository

Source: https://libesmtp.github.io/download.html

Use this command to clone the LibESMTP source code repository from GitHub.

```bash
$ git clone https://github.com/libesmtp/libESMTP.git

```

--------------------------------

### by_mode

Source: https://libesmtp.github.io/reference/_kdoc/libesmtp.html

Enumeration for DELIVERBY (RFC 2852) extension delivery flags.

```APIDOC
## by_mode

### Description
DELIVERBY (RFC 2852) extension flags.

### Constants
- **By_NOTSET** - Deliver-by notification not requested.
- **By_NOTIFY** - FIXME
- **By_RETURN** - FIXME
```

--------------------------------

### Python Factory Method for Adding Messages

Source: https://libesmtp.github.io/critique.html

Demonstrates using a factory method pattern in Python for adding messages to an SMTP session, which is closer to the C API and potentially more intuitive.

```python
message = session.add_message()

```

--------------------------------

### auth_create_context

Source: https://libesmtp.github.io/reference/_kdoc/auth-client.html

Creates a new authentication context. This context is used to manage authentication-specific data and settings.

```APIDOC
## auth_create_context

### Description
Create a new authentication context.

### Parameters
`void` - no arguments

### Returns
The `typedef auth_context_t`.
```

--------------------------------

### smtp_deliverby_set_mode

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Configures delivery tracing and conditions for the Deliver By extension. If the specified time is before the server's earliest guaranteed delivery time, an event will be emitted, and the application may adjust the latest acceptable delivery time.

```APIDOC
## smtp_deliverby_set_mode

### Description
Set delivery tracing and conditions. 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.

### Method
(Not applicable, C function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **message** (smtp_message_t) - The message.
- **time** (long) - Deliver by specified time.
- **mode** (enum by_mode) - Delivery mode.
- **trace** (int) - Trace mode.

### Return
Non zero on success, zero on failure.

### Callbacks
`SMTP_EV_DELIVERBY_EXPIRED`
```

--------------------------------

### Define CONFIG for XDG Layout

Source: https://libesmtp.github.io/reference/certificates.html

This shell command defines the CONFIG variable according to the XDG Base Directory Specification, used for locating libESMTP configuration files.

```shell
CONFIG=${XDG_CONFIG_HOME:-$HOME/.config}/libesmtp
```

--------------------------------

### Python Property for Reverse Path Mailbox

Source: https://libesmtp.github.io/critique.html

Illustrates how a reverse path mailbox could be expressed as a property in Python, assuming libESMTP provides accessors for internal variables.

```python
message.reverse_path = 'brian@example.org'
print(message.reverse_path)

```

--------------------------------

### smtp_starttls_set_password_cb

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Sets the OpenSSL password callback function for handling password prompts during TLS/SSL negotiation. If not set, OpenSSL may default to prompting the user on the tty, which is often undesirable.

```APIDOC
## smtp_starttls_set_password_cb

### Description
Set password callback function for OpenSSL. Unusually this API does not require a `typedef smtp_session_t` as the data it sets is global.
N.B. If this API is not called and OpenSSL requires a password, it will supply a default callback which prompts on the user’s tty. This is likely to be undesired behaviour, so the app should supply a callback using this function.

### Parameters
#### Parameters
- **cb** (smtp_starttls_passwordcb_t) - Password callback with signature `smtp_starttls_passwordcb_t`.
- **arg** (void *) - User data passed to the callback.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### smtp_version

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Retrieves the libESMTP version information. The specific version returned depends on the 'what' parameter.

```APIDOC
## smtp_version

### Description
Identify libESMTP version.

### Parameters
#### Parameters
- **buf** (void *) - Buffer to receive version string.
- **len** (size_t) - Length of buffer.
- **what** (int) - Which version information to be retrieved. Possible values include Ver_VERSION, Ver_SO_VERSION, and Ver_LT_VERSION.

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

--------------------------------

### no_peer_certificate

Source: https://libesmtp.github.io/reference/tlsevents.html

Callback invoked when the peer does not present a certificate. The application can choose to accept or reject the connection.

```APIDOC
## no_peer_certificate

### Description
Report that peer did not present a certficate. By default libESMTP will reject the connection.

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Method
Callback function

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - Equal to `SMTP_EV_NO_PEER_CERTIFICATE`
- **arg** (void *) - application data (closure) specified to smtp_set_eventcb().
- **ok** (int *) - Set zero to quit SMTP session, non-zero to continue.

### Response
N/A

### Response Example
N/A
```

--------------------------------

### smtp_create_session

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Creates a new libESMTP session descriptor to maintain internal state for an SMTP session. Returns a new session or NULL on failure.

```APIDOC
## smtp_create_session

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

### Method
`smtp_create_session`

### Parameters
`void` - no arguments

### Return
A new SMTP session or `NULL` on failure.
```

--------------------------------

### auth_client_enabled

Source: https://libesmtp.github.io/reference/_kdoc/auth-client.html

Checks if SASL is usable by performing various checks on the authentication context. Note that this does not verify loaded plugins. Returns non-zero if SASL is usable, zero otherwise.

```APIDOC
## auth_client_enabled

### Description
Perform various checks to ensure SASL is usable.

### Parameters
`auth_context_t context` - The authentication context.

### Returns
Non-zero if the SASL is usable, zero otherwise.
```

--------------------------------

### smtp_ev_rcptstatus callback

Source: https://libesmtp.github.io/reference/events.html

Callback function for reporting MTA status for the RCPT TO:<> command.

```APIDOC
void smtp_ev_rcptstatus(smtp_session_t session, int event_no, void *arg, const char *mailbox, smtp_recipient_t recipient)

**Parameters** 

`smtp_session_t session`
    
The session. 

`int event_no`
    
Equal to `SMTP_EV_RCPTSTATUS` 

`void *arg`
    
application data (closure) specified to smtp_set_eventcb(). 

`const char *mailbox`
    
The reverse path mailbox. 

`smtp_recipient_t recipient`
    
The **smtp_recipient_t**

**Description**
Report MTA status for the RCPT TO:<> command. The actual status code may be retrieved with smtp_recipient_status().
```

--------------------------------

### ev_extna_2_cb

Source: https://libesmtp.github.io/reference/events.html

Called when a requested SMTP extension is not supported by the MTA, specifically for SMTP_EV_EXTNA_BINARYMIME or SMTP_EV_EXTNA_8BITMIME. It also handles SMTP_EV_EXTNA_STARTTLS if TLS is required but not supported.

```APIDOC
## ev_extna_2_cb

### Description
Issued if a requested SMTP extension is not supported by the MTA. It is not possible to change default behavious in these cases since the message requires an eight-bit-clean transport which is not available unless one of these extensions are supported. If **event_no** is SMTP_EV_EXTNA_STARTTLS, the application has required the use of a TLS connection but this is not supported by the MTA.

### Signature
`void ev_extna_2_cb(smtp_session_t session, int event_no, void *arg)`

### Parameters
#### Path Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - One of `SMTP_EV_EXTNA_BINARYMIME` or `SMTP_EV_EXTNA_8BITMIME`.
- **arg** (void *) - Application data (closure) specified to smtp_set_eventcb().
```

--------------------------------

### Set OpenSSL Password Callback

Source: https://libesmtp.github.io/reference/_kdoc/smtp-tls.html

Set a custom password callback function for OpenSSL. If not provided, OpenSSL may prompt the user on the tty, which is often undesirable. This function is global and does not require a `smtp_session_t`.

```c
int smtp_starttls_set_password_cb(smtp_starttls_passwordcb_t cb, void *arg);
```

--------------------------------

### Set DSN Notify Flags

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Configures DSN notification options, allowing for success, failure, or delay notifications, or disabling notifications. Returns non-zero on success, zero on failure.

```c
int smtp_dsn_set_notify(smtp_recipient_t recipient, enum notify_flags flags);
```

--------------------------------

### Associate Session Data with Release Callback

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Associates application data with an SMTP session. The provided release function is called to free or unreference the data when it's changed or the session is destroyed.

```c
void smtp_set_application_data_release(smtp_session_t session, void *data, void (*release)(void*))
```

--------------------------------

### Read Message from File Callback

Source: https://libesmtp.github.io/reference/_kdoc/message-callbacks.html

Callback function to read the message from a file. The message must be RFC 5322 formatted with CRLF line endings and adhere to RFC 5321 line length limitations.

```c
const char *_smtp_message_fp_cb(void **ctx, int *len, void *arg)
```

--------------------------------

### Python Iteration Over Messages and Recipients

Source: https://libesmtp.github.io/critique.html

This Python code shows how to iterate over messages and their recipients to print status information, leveraging hypothetical iterator support in libESMTP bindings.

```python
session.start()

for message in session.messages():
    print('From:', message.reverse_path)
    for recipient in message.recipients():
        print('To:', recipient.mailbox, recipient.status)


```

--------------------------------

### auth_set_mechanism

Source: https://libesmtp.github.io/reference/_kdoc/auth-client.html

Selects the authentication mechanism after performing checks for acceptable security levels. Returns non-zero on success.

```APIDOC
## auth_set_mechanism

### Description
Perform checks, including acceptable security levels and select the authentication mechanism if successful.

### Parameters
`auth_context_t context` - The authentication context.
`const char *name` - Name of the authentication mechanism.

### Returns
Zero on failure, non-zero on success.
```

--------------------------------

### e8bitmime_body

Source: https://libesmtp.github.io/reference/_kdoc/libesmtp.html

Enumeration for message body types related to the 8BITMIME extension.

```APIDOC
## e8bitmime_body

### Description
8BITMIME extension flags.

### Constants
- **E8bitmime_NOTSET** - Body type not declared.
- **E8bitmime_7BIT** - Body conforms with RFC 5322.
- **E8bitmime_8BITMIME** - Body uses 8 bit encoding.
- **E8bitmime_BINARYMIME** - Body uses BINARYMIME encoding.
```

--------------------------------

### auth_set_mechanism_flags

Source: https://libesmtp.github.io/reference/_kdoc/auth-client.html

Configures authentication mechanism flags for a given context. Allows setting and clearing specific flags, with AUTH_PLUGIN_EXTERNAL being an excluded flag. Returns non-zero on success.

```APIDOC
## auth_set_mechanism_flags

### Description
Configure authentication mechanism flags which may affect operation of the authentication modules.

### Parameters
`auth_context_t context` - The authentication context.
`unsigned set` - Flags to set.
`unsigned clear` - Flags to clear.

### Returns
Zero on failure, non-zero on success.
```

--------------------------------

### notify_flags

Source: https://libesmtp.github.io/reference/_kdoc/libesmtp.html

Enumeration for DSN notification conditions.

```APIDOC
## notify_flags

### Description
DSN notify flags.

### Constants
- **Notify_NOTSET** - Notify options not requested.
- **Notify_NEVER** - Never notify.
- **Notify_SUCCESS** - Notify delivery success.
- **Notify_FAILURE** - Notify delivery failure.
- **Notify_DELAY** - Notify delivery is delayed.
```

--------------------------------

### smtp_enumerate_messages

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Calls a provided callback function for each message currently in the SMTP session. Returns non-zero on success, zero on failure.

```APIDOC
## smtp_enumerate_messages

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

### Method
`smtp_enumerate_messages(smtp_session_t session, smtp_enumerate_messagecb_t cb, void *arg)`

### Parameters
* **session** (`smtp_session_t`) - The session.
* **cb** (`smtp_enumerate_messagecb_t`) - callback function
* **arg** (`void *`) - user data passed to the callback

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### Python Dictionary Comprehension for Recipient Status

Source: https://libesmtp.github.io/critique.html

A Python dictionary comprehension to efficiently map recipient mailboxes to their statuses.

```python
status = {recipient.mailbox: recipient.status for recipient in message.recipients()}

```

--------------------------------

### smtp_set_hostname

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Sets the local host's name for the session. If hostname is NULL, uname() is used. Returns non-zero on success, zero on failure.

```APIDOC
## smtp_set_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`.

### Method
`smtp_set_hostname(smtp_session_t session, const char *hostname)`

### Parameters
* **session** (`smtp_session_t`) - The session.
* **hostname** (`const char *`) - The local hostname.

### Return
Zero on failure, non-zero on success.
```

--------------------------------

### smtp_get_application_data

Source: https://libesmtp.github.io/reference/_kdoc/smtp-api.html

Retrieves the application data associated with an SMTP session.

```APIDOC
## smtp_get_application_data

### Description
Get application data from the session.

### Parameters
- **session** (smtp_session_t) - The session.

### Return
Previously set application data or NULL
```

--------------------------------

### ev_extna_cb

Source: https://libesmtp.github.io/reference/events.html

Triggered when a requested SMTP extension is not supported by the MTA. This callback handles events like SMTP_EV_EXTNA_DSN, SMTP_EV_EXTNA_CHUNKING, or SMTP_EV_EXTNA_ETRN.

```APIDOC
## ev_extna_cb

### Description
Issued if a requested SMTP extension is not supported by the MTA. **event_no** is one of SMTP_EV_EXTNA_DSN, SMTP_EV_EXTNA_CHUNKING or SMTP_EV_EXTNA_ETRN. The value pointed to by **quit** may be used to determine whether the default action is to quit the protocol, and may be set to change this, non-zero means the protocol session will quit.

### Signature
`void ev_extna_cb(smtp_session_t session, int event_no, void *arg, int *quit)`

### Parameters
#### Path Parameters
- **session** (smtp_session_t) - The session.
- **event_no** (int) - One of `SMTP_EV_EXTNA_DSN`, `SMTP_EV_EXTNA_CHUNKING` or `SMTP_EV_EXTNA_ETRN`.
- **arg** (void *) - Application data (closure) specified to smtp_set_eventcb().
- **quit** (int *) - Set non-zero to quit SMTP session, zero to continue.
```