### Build and install the Android demo app

Source: https://github.com/dinhvh/libetpan/blob/master/build-android/README.md

Run these shell commands from the build-android/example directory to build and install the debug APK. Set ANDROID_NDK to your NDK path, stage the prebuilt libraries with prepare-libs.sh, then use Gradle to install or assemble the debug APK.

```shell
# 1. Build the native libraries first (see above) so the artifacts exist.
export ANDROID_NDK=$HOME/Library/Android/sdk/ndk/27.1.12297006

cd build-android/example

# 2. Stage the prebuilt .a files + headers into app/src/main/cpp/prebuilt/
./prepare-libs.sh

# 3. Build / install the debug APK (needs a device or emulator for install)
./gradlew installDebug      # or: ./gradlew assembleDebug

```

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

### Example: SSL Connection

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsnntp.md

Example showing how to create an NNTP session, connect via SSL, and switch to reader mode.

```APIDOC
## Example: SSL Connection

### Description
Example showing how to create an NNTP session, connect via SSL, and switch to reader mode.

### Code
```c
newsnntp * n = newsnntp_new(0, NULL);
if (newsnntp_ssl_connect(n, "news.example.com", 563) == NEWSNNTP_NO_ERROR) {
    newsnntp_mode_reader(n);
    /* ... */
}
newsnntp_free(n);
```
```

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

### Install dependencies on Debian/Ubuntu

Source: https://github.com/dinhvh/libetpan/blob/master/tests/fuzz/README.md

Install required packages for building libetpan with clang and autotools.

```bash
sudo apt install clang autotools-dev libtool autoconf automake pkg-config
```

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

### IDLE usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap-extensions.md

Example of using the IDLE extension: check support, enter IDLE, select on the file descriptor, and send DONE.

```c
if (mailimap_has_idle(session)) {
    mailimap_idle(session);
    fd_set fds; FD_ZERO(&fds); FD_SET(mailimap_idle_get_fd(session), &fds);
    select(mailimap_idle_get_fd(session) + 1, &fds, NULL, NULL, &tv);
    mailimap_idle_done(session);
}
```

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

### IMAP storage connection example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailstorage.md

Example showing how to create a storage, initialize it as an IMAP storage, connect, and then disconnect and free. Uses imap_mailstorage_init with TLS and plain authentication.

```c
struct mailstorage * storage = mailstorage_new("my-imap");
imap_mailstorage_init(storage, "imap.example.com", 993, NULL,
                      CONNECTION_TYPE_TLS, IMAP_AUTH_TYPE_PLAIN,
                      "user", "password", 0, NULL);
if (mailstorage_connect(storage) == MAIL_NO_ERROR) {
    /* ... */
}
mailstorage_disconnect(storage);
mailstorage_free(storage);
```

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

### mailhttp usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/data-types.md

Shows how to create a default transport, build a GET request, perform it, and free the response, request, and transport. The response body and status code are available after a successful call.

```c
struct mailhttp_transport * transport = NULL;
mailhttp_transport_new_default(&transport);
struct mailhttp_request * req = mailhttp_request_new("GET", "https://example.com/rss");
struct mailhttp_response * resp = NULL;
int r = mailhttp_perform(transport, req, &resp);
if (r == MAILHTTP_NO_ERROR) {
    /* resp->status_code, resp->body, resp->body_len */
    mailhttp_response_free(resp);
}
mailhttp_request_free(req);
mailhttp_transport_free(transport);
```

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

### IMAP storage initialization example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/configuration.md

Example of creating an IMAP storage with mailstorage_new and imap_mailstorage_init. Uses CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN, and enables caching with a cache directory.

```c
struct mailstorage * storage = mailstorage_new("imap");
imap_mailstorage_init(storage, "imap.example.com", 0, NULL,
                      CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN,
                      "user", "password", 1, "/var/cache/etpan");
```

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

### Install build tools on Ubuntu

Source: https://github.com/dinhvh/libetpan/blob/master/DEPENDENCIES.md

Installs the required build tools for Linux: build-essential, autoconf, automake, libtool, and pkg-config.

```sh
sudo apt update
sudo apt install build-essential autoconf automake libtool pkg-config
```

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

### mailmessage usage example (new, init, free)

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailmessage.md

Shows the typical usage pattern: create a message, initialize it with a session and driver, use fetch functions, then free. The example passes indx=1 and size=0.

```c
mailmessage * msg = mailmessage_new();
mailmessage_init(msg, session, driver, 1, 0);
/* ... use fetch functions ... */
mailmessage_free(msg);
```

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

### Example: Listing messages with request builder

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailgmail.md

Example showing how to build a message list request and call mailgmail_list_messages.

```APIDOC
## Example: Listing messages with request builder

### Description
Demonstrates creating a message list request, setting query and page token, and calling mailgmail_list_messages.

### Code Example
```c
struct mailgmail_message_list_request * req = mailgmail_message_list_request_new();
mailgmail_message_list_request_set_query(req, "from:alice newer_than:7d");
mailgmail_message_list_request_set_page_token(req, page_token);
struct mailgmail_message_list * list = NULL;
if (mailgmail_list_messages(g, req, &list) == MAILGMAIL_NO_ERROR) {
    /* list->messages (clist of mailgmail_message_summary*),
       list->next_page_token */
}
mailgmail_message_list_request_free(req);
```
```

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

### Session usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailsmtp.md

Example of creating a session, connecting to a mailstream, and then quitting and freeing the session. The connection check uses MAILSMTP_NO_ERROR.

```c
mailsmtp * session = mailsmtp_new(0, NULL);
if (mailsmtp_connect(session, stream) == MAILSMTP_NO_ERROR) {
    /* ... */
}
mailsmtp_quit(session);
mailsmtp_free(session);
```

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

### mailpop3 SSL connection example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpop3.md

Example of connecting to a POP3 server over TLS using mailpop3_ssl_connect, then logging in and cleaning up.

```c
mailpop3 * f = mailpop3_new(0, NULL);
if (mailpop3_ssl_connect(f, "pop.example.com", 995) == MAILPOP3_NO_ERROR) {
    mailpop3_login(f, "user", "password");
    /* ... */
}
mailpop3_quit(f);
mailpop3_free(f);
```

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

### Example: connect to folder, get messages list, get envelopes, disconnect, free

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailstorage.md

Example usage of the mailfolder API. Creates a folder for 'INBOX', connects, retrieves the messages list, fills in envelopes, then disconnects and frees. The comment notes that list->msg_tab is a carray of mailmessage*.

```c
struct mailfolder * folder = mailfolder_new(storage, "INBOX", "INBOX");
if (mailfolder_connect(folder) == MAIL_NO_ERROR) {
    struct mailmessage_list * list = NULL;
    if (mailfolder_get_messages_list(folder, &list) == MAIL_NO_ERROR) {
        mailfolder_get_envelopes_list(folder, list);
        /* list->msg_tab is a carray of mailmessage* */
    }
}
mailfolder_disconnect(folder);
mailfolder_free(folder);
```

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

### mailjmap OAuth2 login usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailjmap.md

Example of creating a mailjmap session, discovering the JMAP endpoint, and logging in with OAuth2 using an access token.

```c
mailjmap * jmap = mailjmap_new(0, NULL);
mailjmap_discover(jmap, "user@example.com", NULL);
mailjmap_login_oauth2(jmap, "user@example.com", "ya29.access.token");
```

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

### Install build tools on macOS

Source: https://github.com/dinhvh/libetpan/blob/master/DEPENDENCIES.md

Installs Xcode command line tools and Homebrew packages for autoconf, automake, libtool, and pkg-config.

```sh
xcode-select --install
brew install autoconf automake libtool pkg-config
```

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

### Example: list, retrieve, delete messages with mailpop3

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpop3.md

Shows a typical workflow: call mailpop3_list to get all message info, iterate with carray_count/carray_get, retrieve each message with mailpop3_retr, process the buffer, free it with mailpop3_retr_free, and mark the message deleted with mailpop3_dele. The comment notes that infos must be freed via the driver's list free function.

```c
carray * infos = NULL;
if (mailpop3_list(session, &infos) == MAILPOP3_NO_ERROR) {
    unsigned int i;
    for (i = 0; i < carray_count(infos); i++) {
        struct mailpop3_msg_info * info = carray_get(infos, i);
        char * msg = NULL; size_t len = 0;
        if (mailpop3_retr(session, info->msg_index, &msg, &len) == MAILPOP3_NO_ERROR) {
            /* process msg (len bytes) */
            mailpop3_retr_free(msg);
        }
        mailpop3_dele(session, info->msg_index);
    }
    /* free infos via the driver's list free function */
}
```

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

### S/MIME usage example: verify signature

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Example showing how to create a mailsmime object, add trusted certificates and keys, verify a MIME entity, and check the verification status. The result must be freed with mailsmime_result_free.

```c
struct mailsmime * smime = mailsmime_new();
mailsmime_add_trusted_cert_file(smime, "ca.pem");
mailsmime_add_cert_file(smime, "bob@example.com", "bob.pem");
mailsmime_set_private_key_file(smime, "bob@example.com",
    "bob.pem", "bob.key", "pass");
struct mailsmime_result * res = NULL;
if (mailsmime_verify(smime, mime, &res) == MAILSMIME_NO_ERROR) {
    if (mailsmime_result_status(res) == MAILSMIME_VERIFY_VALID) {
        /* signature is valid */
    }
    mailsmime_result_free(res);
}
```

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

### Get MIME structure and fetch section

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailmessage.md

Example of getting the MIME structure and fetching a section. The mime pointer is owned by the message and must not be freed directly. The fetched part buffer is freed with mailmessage_fetch_result_free().

```c
struct mailmime * mime = NULL;
mailmessage_get_bodystructure(msg, &mime);
if (mime != NULL) {
    char * part = NULL; size_t plen = 0;
    mailmessage_fetch_section(msg, mime, &part, &plen);
    mailmessage_fetch_result_free(msg, part);
}
```

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

### Build on macOS with configure and make

Source: https://github.com/dinhvh/libetpan/blob/master/README.md

Install Autoconf, Automake, and Libtool, then run autogen.sh, configure, and make to build on macOS.

```sh
./autogen.sh
./configure
make
```

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

### Profile and Label Functions: mailgmail_get_profile, mailgmail_list_labels, mailgmail_get_label

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailgmail.md

Declarations for retrieving the user profile, listing labels, and getting a specific label by ID. The corresponding HTTP calls are GET /gmail/v1/users/{userId}/profile, GET /gmail/v1/users/{userId}/labels, and GET /gmail/v1/users/{userId}/labels/{id}.

```c
LIBETPAN_EXPORT
int mailgmail_get_profile(mailgmail * session,
    struct mailgmail_profile ** result);

LIBETPAN_EXPORT
int mailgmail_list_labels(mailgmail * session,
    struct mailgmail_label_list ** result);

LIBETPAN_EXPORT
int mailgmail_get_label(mailgmail * session,
    const char * label_id,
    struct mailgmail_label ** result);
```

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

### Initialize GnuPG and create engine

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailprivacy.md

Example showing how to create a mailprivacy instance, initialize the GnuPG protocol, create an engine, and clean up. The mailprivacy_new call takes a path and a flag; the engine is used for mail operations before being freed.

```c
struct mailprivacy * privacy = mailprivacy_new("/tmp/libetpan", 1);
mailprivacy_gnupg_init(privacy);
struct mailengine * engine = libetpan_engine_new(privacy);
/* ... use engine ... */
libetpan_engine_free(engine);
mailprivacy_gnupg_done(privacy);
mailprivacy_free(privacy);
```

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

### mailpgp lifecycle example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Shows the basic lifecycle of a mailpgp object with creation and destruction, plus the header to include.

```c
#include <libetpan/mailpgp.h>
int main() {
  struct mailpgp * pgp = mailpgp_new();
  /* ... */
  mailpgp_free(pgp);
  return 0;
}

```

```c
#include <libetpan/mailpgp.h>
#include <stdio.h>
int main() {
  struct mailpgp * pgp = mailpgp_new();
  /* ... */
  return 0;
}

```

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

### Run jmap-sample with environment variables

Source: https://github.com/dinhvh/libetpan/blob/master/doc/JMAP.md

Run the sample with JMAP_SESSION_URL, JMAP_EMAIL, and JMAP_ACCESS_TOKEN. Omit JMAP_SESSION_URL and set JMAP_EMAIL to use .well-known/jmap discovery.

```sh
JMAP_SESSION_URL=https://example.com/jmap/session \
JMAP_EMAIL=user@example.com \
JMAP_ACCESS_TOKEN=token \
./tests/jmap-sample
```

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

### Build libEtPan with Visual Studio using msbuild

Source: https://github.com/dinhvh/libetpan/blob/master/build-windows/README.md

Builds libEtPan on Windows with Visual Studio. Requires Visual Studio 2013, 2015, or 2017 (Community edition is sufficient) and the binary dependencies (zlib, OpenSSL, Cyrus SASL) downloaded from the provided links. The command is run from the libetpan directory after cloning or unpacking the repository.

```shell
msbuild libetpan.sln /p:Configuration=Release /p:Platform=Win32
```

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

### Prepare Xcode workspace on macOS/iOS

Source: https://github.com/dinhvh/libetpan/blob/master/README.md

Install Xcode and CMake, then run bootstrap.sh from the build-mac directory and open the generated Xcode workspace.

```sh
cd build-mac
./bootstrap.sh
open libetpan.xcworkspace
```

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

### Output layout of build/libetpan-android/

Source: https://github.com/dinhvh/libetpan/blob/master/build-android/README.md

Shows the directory structure containing headers and static libraries for each ABI.

```text
libetpan-android/
  include/libetpan/libetpan-config.h
  libs/arm64-v8a/libetpan.a
  libs/armeabi-v7a/libetpan.a
  libs/x86/libetpan.a
  libs/x86_64/libetpan.a
```

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

### Install tools for rebuilding dependency XCFrameworks

Source: https://github.com/dinhvh/libetpan/blob/master/DEPENDENCIES.md

Installs Xcode command line tools and Homebrew packages needed when rebuilding dependency XCFrameworks.

```sh
xcode-select --install
brew install cmake autoconf automake libtool
```

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

### mailimap_fetch usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Example of fetching all message attributes and iterating over the result. The result must be freed with mailimap_fetch_list_free() and the fetch type with mailimap_fetch_type_free().

```c
struct mailimap_fetch_type * ft = mailimap_fetch_type_new_all();
clist * msgs = NULL;
int r = mailimap_fetch(session, set, ft, &msgs);
if (r != MAILIMAP_NO_ERROR) {
    /* handle failure */
}
clistiter * cur;
for (cur = clist_begin(msgs); cur != NULL; cur = clist_next(cur)) {
    struct mailimap_msg_att * att = clist_content(cur);
    /* inspect att->att_list */
}
mailimap_fetch_list_free(msgs);
mailimap_fetch_type_free(ft);
```

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

### Downloading and parsing a feed

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Example of creating a feed, setting its URL, and updating it. If successful, feed metadata and items are populated.

```c
struct newsfeed * feed = newsfeed_new();
newsfeed_set_url(feed, "https://example.com/feed.xml");
if (newsfeed_update(feed, 0) == NEWSFEED_NO_ERROR) {
    /* feed metadata and items are populated */
}
```

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

### mailstream_low_setup_idle

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailstream.md

Sets up idle on the low-level stream.

```APIDOC
## mailstream_low_setup_idle

### Description
Sets up idle on the low-level stream.

### Function Signature
```c
LIBETPAN_EXPORT
int mailstream_low_setup_idle(mailstream_low * low);
```

### Parameters
- **low** (mailstream_low *) - Required - The low-level stream.

### Return Value
- **int** - Status code (0 on success, non-zero on failure).
```

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

### Build "+FLAGS (\Seen \Flagged)" with mailimap_flag_list and mailimap_uid_store

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap-helpers.md

Example showing how to create a flag list, add the Seen and Flagged flags, wrap it in a mailimap_store_att_flags, and pass it to mailimap_uid_store.

```c
/* Build "+FLAGS (\Seen \Flagged)" */
struct mailimap_flag_list * flags = mailimap_flag_list_new_empty();
mailimap_flag_list_add(flags, mailimap_flag_new_seen());
mailimap_flag_list_add(flags, mailimap_flag_new_flagged());
struct mailimap_store_att_flags * att = mailimap_store_att_flags_new_add_flags(flags);
mailimap_uid_store(session, set, att);
```

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

### mailmime_parse usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailmime.md

Example of parsing a complete MIME message into a struct mailmime tree, checking for MAILIMF_NO_ERROR, walking the tree, and freeing the result with mailmime_free.

```c
struct mailmime * mime = NULL;
size_t pos = 0;
if (mailmime_parse(raw, len, &pos, &mime) == MAILIMF_NO_ERROR) {
    /* walk mime->mm_data / mime->mm_content_type */
    mailmime_free(mime);
}
```

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

### Link order for libetpan.a

Source: https://github.com/dinhvh/libetpan/blob/master/build-android/README.md

Shows the required link order for consumers before providers. libetpan.a is not self-contained; it requires additional static libraries and system libs.

```text
etpan  rnp  curl  xml2  json-c  sasl2  ssl  crypto  icuuc  icudata  z  log
```

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

### mailimap_search usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Example of searching for messages from "alice" and freeing the result. The charset parameter is NULL, and the result must be freed with mailimap_search_result_free().

```c
struct mailimap_search_key * key = mailimap_search_key_new_from("alice");
clist * found = NULL;
if (mailimap_search(session, NULL, key, &found) == MAILIMAP_NO_ERROR) {
    /* found is a clist of uint32_t* */
    mailimap_search_result_free(found);
}
mailimap_search_key_free(key);
```

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

### Session lifecycle usage example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpop3.md

Shows creating a session with no progress callback, connecting to a mailstream, and then quitting and freeing the session. The connection check uses MAILPOP3_NO_ERROR.

```c
mailpop3 * session = mailpop3_new(0, NULL);
if (mailpop3_connect(session, stream) == MAILPOP3_NO_ERROR) {
    /* ... */
}
mailpop3_quit(session);
mailpop3_free(session);
```

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

### Install optional feature dependencies on macOS

Source: https://github.com/dinhvh/libetpan/blob/master/DEPENDENCIES.md

Installs optional dependencies for TLS, SASL, ICU, cache databases, XML, JSON, curl, zlib, and RNP via Homebrew.

```sh
brew install \
  openssl@3 \
  gnutls \
  cyrus-sasl \
  icu4c \
  berkeley-db \
  lmdb \
  libxml2 \
  json-c \
  curl \
  zlib \
  rnp
```

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

### Connect with mailimap_ssl_connect and login

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Example of establishing a TLS connection with mailimap_ssl_connect, then logging in if the connection returns MAILIMAP_NO_ERROR_NON_AUTHENTICATED. Ends with logout and free.

```c
mailimap * session = mailimap_new(0, NULL);
int r = mailimap_ssl_connect(session, "imap.example.com", 993);
if (r == MAILIMAP_NO_ERROR_NON_AUTHENTICATED) {
    r = mailimap_login(session, "user", "password");
}
/* ... */
mailimap_logout(session);
mailimap_free(session);
```

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

### Install optional feature dependencies on Ubuntu

Source: https://github.com/dinhvh/libetpan/blob/master/DEPENDENCIES.md

Installs optional dependencies for TLS, SASL, ICU, cache databases, XML, JSON, curl, zlib, RNP, and liblockfile on Ubuntu.

```sh
sudo apt install \
  libssl-dev \
  libgnutls28-dev \
  libsasl2-dev \
  libicu-dev \
  libdb-dev \
  liblmdb-dev \
  libxml2-dev \
  libjson-c-dev \
  libcurl4-openssl-dev \
  zlib1g-dev \
  librnp-dev \
  liblockfile-dev
```

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

### Message Functions: mailgmail_list_messages, mailgmail_get_message, mailgmail_get_attachment

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailgmail.md

Declarations for listing messages, retrieving a single message, and fetching an attachment. The corresponding HTTP calls are GET /gmail/v1/users/{userId}/messages, GET /gmail/v1/users/{userId}/messages/{id}, and GET /gmail/v1/users/{userId}/messages/{id}/attachments/{attachmentId}. The request parameter may be NULL for default behavior.

```c
LIBETPAN_EXPORT
int mailgmail_list_messages(mailgmail * session,
    struct mailgmail_message_list_request * request,
    struct mailgmail_message_list ** result);

LIBETPAN_EXPORT
int mailgmail_get_message(mailgmail * session,
    const char * message_id,
    struct mailgmail_message_get_request * request,
    struct mailgmail_message ** result);

LIBETPAN_EXPORT
int mailgmail_get_attachment(mailgmail * session,
    const char * message_id,
    const char * attachment_id,
    struct mailgmail_attachment ** result);
```

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

### Example: listing messages with mailgmail_list_messages

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailgmail.md

Shows how to create a message list request, set a query and page token, call mailgmail_list_messages, and handle the result. The list contains message summaries and a next page token for pagination. The request must be freed after use.

```c
struct mailgmail_message_list_request * req = mailgmail_message_list_request_new();
mailgmail_message_list_request_set_query(req, "from:alice newer_than:7d");
mailgmail_message_list_request_set_page_token(req, page_token);
struct mailgmail_message_list * list = NULL;
if (mailgmail_list_messages(g, req, &list) == MAILGMAIL_NO_ERROR) {
    /* list->messages (clist of mailgmail_message_summary*),
       list->next_page_token */
}
mailgmail_message_list_request_free(req);
```

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

### Passphrase callback and key file addition

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

An example of setting a passphrase callback and adding key files. The callback returns a hardcoded passphrase; the secret key file is added with an explicit passphrase.

```c
static const char * on_passphrase(const char * key_id, void * ctx) {
    return "hunter2";
}
struct mailpgp * pgp = mailpgp_new();
mailpgp_set_passphrase_callback(pgp, on_passphrase, NULL);
mailpgp_add_public_key_file(pgp, "pub.asc");
mailpgp_add_secret_key_file(pgp, "sec.asc", "hunter2");
```

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

### Feed Metadata Functions

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Functions to get and set feed metadata such as title, description, language, author, generator, and date. Also includes a function to get the last HTTP response code.

```APIDOC
## Feed Metadata Functions

### Description
These functions manage the metadata of a newsfeed, including title, description, language, author, generator, and date. The response code function returns the HTTP status of the last fetch.

### Function Signatures
```c
int newsfeed_set_title(struct newsfeed * feed, const char * title);
const char * newsfeed_get_title(struct newsfeed * feed);
int newsfeed_set_description(struct newsfeed * feed, const char * description);
const char * newsfeed_get_description(struct newsfeed * feed);
int newsfeed_set_language(struct newsfeed * feed, const char * language);
const char * newsfeed_get_language(struct newsfeed * feed);
int newsfeed_set_author(struct newsfeed * feed, const char * author);
const char * newsfeed_get_author(struct newsfeed * feed);
int newsfeed_set_generator(struct newsfeed * feed, const char * generator);
const char * newsfeed_get_generator(struct newsfeed * feed);
void newsfeed_set_date(struct newsfeed * feed, time_t date);
time_t newsfeed_get_date(struct newsfeed * feed);
int newsfeed_get_response_code(struct newsfeed * feed);
```

### Parameters
- **feed** (struct newsfeed *) - Required - The newsfeed object.
- **title** (const char *) - Required for setter - The title to set.
- **description** (const char *) - Required for setter - The description to set.
- **language** (const char *) - Required for setter - The language to set.
- **author** (const char *) - Required for setter - The author to set.
- **generator** (const char *) - Required for setter - The generator to set.
- **date** (time_t) - Required for setter - The date to set.

### Return Values
- **int** - Status code for setters (0 on success, non-zero on failure).
- **const char *** - Pointer to the string value for getters (title, description, language, author, generator).
- **time_t** - The date value for `newsfeed_get_date`.
- **int** - The HTTP response code for `newsfeed_get_response_code`.
```

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

### db_mailstorage_init

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/configuration.md

Initializes a database-backed mail storage.

```APIDOC
## db_mailstorage_init

### Description
Initializes a database-backed mail storage.

### Function Signature
```c
int db_mailstorage_init(struct mailstorage * storage,
    char * db_pathname);
```

### Parameters
- **storage** (struct mailstorage *) - Required - Pointer to the mail storage object.
- **db_pathname** (char *) - Required - Path to the database.

### Return Value
Returns an integer indicating success (0) or failure (non-zero).
```

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

### mailsmime_certificate_issuer

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the issuer from a certificate.

```APIDOC
## mailsmime_certificate_issuer

### Description
Gets the issuer from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_issuer(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Issuer string.

```

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

### Build libetpan with AddressSanitizer

Source: https://github.com/dinhvh/libetpan/blob/master/tests/fuzz/README.md

Configure and build libetpan with ASan instrumentation. The static library is produced at src/.libs/libetpan.a.

```bash
cd <libetpan-root>
./autogen.sh
CC=clang CXX=clang++ ./configure \
    CFLAGS="-g -O1 -fsanitize=address" \
    CXXFLAGS="-g -O1 -fsanitize=address" \
    LDFLAGS="-fsanitize=address"
make -j$(nproc)
```

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

### mailsmtp_socket_starttls_with_callback

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailsmtp.md

Upgrades to TLS using STARTTLS with a callback for SSL context configuration.

```APIDOC
## mailsmtp_socket_starttls_with_callback

### Description
Upgrades to TLS using STARTTLS with a callback for SSL context configuration.

### Method
C function

### Signature
```c
int mailsmtp_socket_starttls_with_callback(mailsmtp * session,
    void (* callback)(struct mailstream_ssl_context * ssl_context, void * data), void * data);
```

### Parameters
- **session** (mailsmtp *) - Required - The SMTP session.
- **callback** (function pointer) - Required - Callback to configure the SSL context. Signature: `void (*)(struct mailstream_ssl_context * ssl_context, void * data)`.
- **data** (void *) - Required - User data passed to the callback.

### Returns
int - Returns `MAILSMTP_NO_ERROR` on success, or an error code on failure.
```

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

### mailsmime_certificate_subject

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the subject from a certificate.

```APIDOC
## mailsmime_certificate_subject

### Description
Gets the subject from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_subject(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Subject string.

```

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

### mbox_mailstorage_init

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/configuration.md

Initializes an mbox local mail storage.

```APIDOC
## mbox_mailstorage_init

### Description
Initializes an mbox local mail storage.

### Function Signature
```c
int mbox_mailstorage_init(struct mailstorage * storage,
    const char * mb_pathname, int mb_cached,
    const char * mb_cache_directory, const char * mb_flags_directory);
```

### Parameters
- **storage** (struct mailstorage *) - Required - Pointer to the mail storage object.
- **mb_pathname** (const char *) - Required - Path to the mbox file.
- **mb_cached** (int) - Required - Nonzero enables persistent local cache.
- **mb_cache_directory** (const char *) - Required - Cache location.
- **mb_flags_directory** (const char *) - Required - Flags directory.

### Return Value
Returns an integer indicating success (0) or failure (non-zero).
```

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

### mailsmime_certificate_name

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the name from a certificate.

```APIDOC
## mailsmime_certificate_name

### Description
Gets the name from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_name(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Name string.

```

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

### mailprivacy_get_encryption_name

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailprivacy.md

Gets the encryption name.

```APIDOC
## mailprivacy_get_encryption_name

### Description
Gets the encryption name for a given privacy driver and encryption.

### Method
C function

### Signature
```c
char * mailprivacy_get_encryption_name(struct mailprivacy * privacy, char * privacy_driver, char * privacy_encryption);
```

### Parameters
- **privacy** (struct mailprivacy *) - Required - The mailprivacy object.
- **privacy_driver** (char *) - Required - The privacy driver name.
- **privacy_encryption** (char *) - Required - The encryption name.

### Returns
- **char \*** - The encryption name.

```

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

### mailimap_socket_starttls_with_server_name_callback

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Upgrades to TLS with SNI and a callback for SSL context configuration.

```APIDOC
## mailimap_socket_starttls_with_server_name_callback

### Description
Upgrades to TLS with SNI and a callback for SSL context configuration.

### Function Signature
```c
int mailimap_socket_starttls_with_server_name_callback(mailimap * f,
    const char * server_name,
    void (* callback)(struct mailstream_ssl_context * ssl_context, void * data), void * data);
```

### Parameters
- **f** (mailimap *) - The IMAP session.
- **server_name** (const char *) - The server name for SNI.
- **callback** (function pointer) - Callback to configure the SSL context.
- **data** (void *) - User data passed to the callback.

### Return Value
Returns an integer status code.
```

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

### newsnntp_get_timeout

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsnntp.md

Gets the timeout of the NNTP session.

```APIDOC
## newsnntp_get_timeout

### Description
Gets the timeout of the NNTP session.

### Method
C function

### Signature
```c
LIBETPAN_EXPORT
time_t newsnntp_get_timeout(newsnntp * session);
```

### Parameters
- **session** (newsnntp *) - Required - The session handle.

### Returns
- **time_t** - The current timeout value.

```

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

### mailimap_socket_starttls_with_callback

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Upgrades to TLS with a callback for SSL context configuration.

```APIDOC
## mailimap_socket_starttls_with_callback

### Description
Upgrades to TLS with a callback for SSL context configuration.

### Function Signature
```c
int mailimap_socket_starttls_with_callback(mailimap * f,
    void (* callback)(struct mailstream_ssl_context * ssl_context, void * data), void * data);
```

### Parameters
- **f** (mailimap *) - The IMAP session.
- **callback** (function pointer) - Callback to configure the SSL context.
- **data** (void *) - User data passed to the callback.

### Return Value
Returns an integer status code.
```

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

### mailsmime_certificate_fingerprint_sha256

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the SHA-256 fingerprint from a certificate.

```APIDOC
## mailsmime_certificate_fingerprint_sha256

### Description
Gets the SHA-256 fingerprint from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_fingerprint_sha256(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
SHA-256 fingerprint string.

```

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

### mailsmime_certificate_not_after

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the not-after date from a certificate.

```APIDOC
## mailsmime_certificate_not_after

### Description
Gets the not-after date from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_not_after(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Not-after date string.

```

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

### mailimap_socket_starttls

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Upgrades an existing plain connection to TLS using STARTTLS.

```APIDOC
## mailimap_socket_starttls

### Description
Upgrades an existing plain connection to TLS using STARTTLS.

### Function Signature
```c
int mailimap_socket_starttls(mailimap * f);
```

### Parameters
- **f** (mailimap *) - The IMAP session.

### Return Value
Returns an integer status code.
```

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

### mailsmime_certificate_not_before

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the not-before date from a certificate.

```APIDOC
## mailsmime_certificate_not_before

### Description
Gets the not-before date from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_not_before(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Not-before date string.

```

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

### mailsmime_certificate_email

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets the email address from a certificate.

```APIDOC
## mailsmime_certificate_email

### Description
Gets the email address from a certificate.

### Method
C function

### Signature
```c
const char * mailsmime_certificate_email(struct mailsmime_certificate * cert);
```

### Parameters
- **cert** (struct mailsmime_certificate *) - Required - The certificate.

### Returns
Email address string.

```

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

### newsnntp connect and quit example

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsnntp.md

Shows a typical usage pattern: create a session with progress disabled, connect to a mailstream, check for NEWSNNTP_NO_ERROR, then quit and free. The stream variable is assumed to be a valid mailstream.

```c
newsnntp * n = newsnntp_new(0, NULL);
if (newsnntp_connect(n, stream) == NEWSNNTP_NO_ERROR) {
    /* ... */
}
newsnntp_quit(n);
newsnntp_free(n);
```

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

### mailstream_low_get_timeout

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailstream.md

Gets the timeout of the mailstream_low stream.

```APIDOC
## mailstream_low_get_timeout

### Description
Gets the timeout of the mailstream_low stream.

### Function Signature
```c
LIBETPAN_EXPORT
time_t mailstream_low_get_timeout(mailstream_low * s);
```

### Parameters
- **s** (mailstream_low *) - Required - The stream.

### Return Value
- **time_t** - The timeout value in seconds.
```

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

### chash_begin, chash_next (Iteration)

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/data-types.md

Iteration functions for the hash table. chash_begin returns an iterator to the first entry, and chash_next advances the iterator. Returns NULL when no more entries exist.

```APIDOC
## chash_begin, chash_next (Iteration)

### Description
Iteration functions for the hash table.

### Function Signatures
```c
LIBETPAN_EXPORT
chashiter * chash_begin(chash /* chashdatum key/value */ * hash);
LIBETPAN_EXPORT
chashiter * chash_next(chash /* chashdatum key/value */ * hash, chashiter * iter);
```

### Parameters
- **hash** (chash*) - Required - The hash table.
- **iter** (chashiter*) - Required (for chash_next) - The current iterator.

### Returns
- **chashiter\*** - Iterator to the first entry (chash_begin) or the next entry (chash_next), or NULL when no more entries exist.
```

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

### newsfeed_item_get_id

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Gets the ID of the newsfeed item.

```APIDOC
## newsfeed_item_get_id

### Description
Gets the ID of the newsfeed item.

### Function Signature
```c
const char * newsfeed_item_get_id(struct newsfeed_item * item);
```

### Parameters
- **item** (struct newsfeed_item *) - Required - The newsfeed item.

### Return Value
- **const char *** - The ID string.
```

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

### Refresh release artifacts

Source: https://github.com/dinhvh/libetpan/blob/master/RELEASE.md

Run this script to refresh release artifacts such as build-windows/libetpan_version.h, build-windows/build_headers.list, and build-spm/include/libetpan/ public headers.

```sh
build-release/prepare-release.sh
```

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

### mailsmtp_socket_starttls_with_server_name_callback

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailsmtp.md

Upgrades to TLS using STARTTLS with server name indication and a callback for SSL context configuration.

```APIDOC
## mailsmtp_socket_starttls_with_server_name_callback

### Description
Upgrades to TLS using STARTTLS with server name indication and a callback for SSL context configuration.

### Method
C function

### Signature
```c
int mailsmtp_socket_starttls_with_server_name_callback(mailsmtp * session,
    const char * server_name,
    void (* callback)(struct mailstream_ssl_context * ssl_context, void * data), void * data);
```

### Parameters
- **session** (mailsmtp *) - Required - The SMTP session.
- **server_name** (const char *) - Required - The server name for SNI.
- **callback** (function pointer) - Required - Callback to configure the SSL context. Signature: `void (*)(struct mailstream_ssl_context * ssl_context, void * data)`.
- **data** (void *) - Required - User data passed to the callback.

### Returns
int - Returns `MAILSMTP_NO_ERROR` on success, or an error code on failure.
```

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

### newsfeed_item_get_author

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Gets the author of the newsfeed item.

```APIDOC
## newsfeed_item_get_author

### Description
Gets the author of the newsfeed item.

### Function Signature
```c
const char * newsfeed_item_get_author(struct newsfeed_item * item);
```

### Parameters
- **item** (struct newsfeed_item *) - Required - The newsfeed item.

### Return Value
- **const char *** - The author string.
```

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

### newsfeed_item_get_summary

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Gets the summary of the newsfeed item.

```APIDOC
## newsfeed_item_get_summary

### Description
Gets the summary of the newsfeed item.

### Function Signature
```c
const char * newsfeed_item_get_summary(struct newsfeed_item * item);
```

### Parameters
- **item** (struct newsfeed_item *) - Required - The newsfeed item.

### Return Value
- **const char *** - The summary string.
```

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

### Backend selection functions

Source: https://github.com/dinhvh/libetpan/blob/master/doc/HTTP.md

Use these functions during process startup to check availability, set the backend, and get the current backend. Apple builds default to MAILHTTP_BACKEND_NSURLSESSION; other builds default to curl. mailhttp_set_backend() returns -1 and leaves the selection unchanged if the requested backend was not compiled.

```c
mailhttp_backend_is_available(MAILHTTP_BACKEND_CURL);
mailhttp_set_backend(MAILHTTP_BACKEND_CURL);
mailhttp_get_backend();
```

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

### newsfeed_item_get_title

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Gets the title of the newsfeed item.

```APIDOC
## newsfeed_item_get_title

### Description
Gets the title of the newsfeed item.

### Function Signature
```c
const char * newsfeed_item_get_title(struct newsfeed_item * item);
```

### Parameters
- **item** (struct newsfeed_item *) - Required - The newsfeed item.

### Return Value
- **const char *** - The title string.
```

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

### mailimap_starttls

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailimap.md

Issues a STARTTLS command so the connection switches to TLS. This does not switch the underlying mailstream.

```APIDOC
## mailimap_starttls

### Description
Issues a STARTTLS command so the connection switches to TLS. This does not switch the underlying mailstream.

### Method
Function

### Signature
```c
LIBETPAN_EXPORT
int mailimap_starttls(mailimap * session);
```

### Parameters
- **session** (mailimap *) - Required - IMAP session.

### Return Value
Returns an int status code.
```

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

### newsfeed_item_get_url

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/newsfeed.md

Gets the URL of the newsfeed item.

```APIDOC
## newsfeed_item_get_url

### Description
Gets the URL of the newsfeed item.

### Function Signature
```c
const char * newsfeed_item_get_url(struct newsfeed_item * item);
```

### Parameters
- **item** (struct newsfeed_item *) - Required - The newsfeed item.

### Return Value
- **const char *** - The URL string.
```

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

### libetpan_engine_new

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailprivacy.md

Creates a new mailengine instance.

```APIDOC
## libetpan_engine_new

### Description
Creates a new mailengine instance that references a mailprivacy object for on-the-fly decryption/encryption of messages.

### Signature
```c
LIBETPAN_EXPORT
struct mailengine * libetpan_engine_new(struct mailprivacy * privacy);
```

### Parameters
- **privacy** (struct mailprivacy *) - Required - The privacy object used for encryption/decryption.

### Return Value
- Returns a pointer to the newly created mailengine, or NULL on failure.

```

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

### Profile Usage Example: mailgmail_get_profile

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailgmail.md

Example of creating a mailgmail session, setting the user to "me" and an OAuth2 token, then retrieving the profile. On success, the profile fields such as email_address and messages_total are available; the profile must be freed with mailgmail_profile_free.

```c
mailgmail * g = mailgmail_new();
mailgmail_set_user(g, "me");
mailgmail_set_oauth2_token(g, "ya29.access.token");
struct mailgmail_profile * profile = NULL;
if (mailgmail_get_profile(g, &profile) == MAILGMAIL_NO_ERROR) {
    /* profile->email_address, profile->messages_total, ... */
    mailgmail_profile_free(profile);
}
```

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

### Provisioning

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailactivesync.md

Functions to perform OPTIONS and Provision operations for device provisioning.

```APIDOC
## mailactivesync_options

### Description
Performs the OPTIONS request to retrieve server capabilities.

### Function Signature
```c
int mailactivesync_options(mailactivesync * session, struct mailactivesync_options ** result);
```

### Parameters
- **session** (mailactivesync *) - Required - The ActiveSync session.
- **result** (struct mailactivesync_options **) - Required - Pointer to store the result.

### Return Value
- **int** - 0 on success, non-zero on failure.

## mailactivesync_provision

### Description
Performs the Provision operation to provision the device.

### Function Signature
```c
int mailactivesync_provision(mailactivesync * session, struct mailactivesync_provision_result ** result);
```

### Parameters
- **session** (mailactivesync *) - Required - The ActiveSync session.
- **result** (struct mailactivesync_provision_result **) - Required - Pointer to store the result.

### Return Value
- **int** - 0 on success, non-zero on failure.
```

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

### mailsmime_result_get_signer

Source: https://github.com/dinhvh/libetpan/blob/master/_autodocs/api-reference/mailpgp-smime.md

Gets a signer certificate from a result object.

```APIDOC
## mailsmime_result_get_signer

### Description
Gets a signer certificate from a result object.

### Method
C function

### Signature
```c
int mailsmime_result_get_signer(struct mailsmime_result * result, unsigned int index, struct mailsmime_certificate ** cert);
```

### Parameters
- **result** (struct mailsmime_result *) - Required - The verification result.
- **index** (unsigned int) - Required - Index of the signer.
- **cert** (struct mailsmime_certificate **) - Required - Output parameter for the certificate.

### Returns
Error code (MAILSMIME_NO_ERROR on success).

```