<!-- review: finished -->

<a id="mail-imap"></a>

# IMAP

The module enables IMAP mail protocol support, allowing the server to interact
with mail storage systems. It establishes connections to IMAP servers, processes
common commands such as listing mailboxes and retrieving messages, and provides
secure authentication and message status management.

<a id="directives-58"></a>

## Directives

<a id="index-0"></a>

<a id="m-imap-auth"></a>

### imap_auth

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_auth` method ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `imap_auth plain;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Sets permitted methods of authentication for IMAP clients. Supported methods are:

| `plain`       | [LOGIN](https://datatracker.ietf.org/doc/html/rfc3501), [AUTH=PLAIN](https://datatracker.ietf.org/doc/html/rfc4616)                        |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `login`       | [AUTH=LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00)                                                          |
| `cram-md5`    | [AUTH=CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). In order for this method to work, the password must be stored unencrypted. |
| `external`    | [AUTH=EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422)                                                                             |
| `xoauth2`     | [AUTH=XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol)                                                                  |
| `oauthbearer` | [AUTH=OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628)                                                                          |

Plain text authentication methods (the `LOGIN` command,
`AUTH=PLAIN`, and `AUTH=LOGIN`) are always enabled, though if the
`plain` and `login` methods are not specified, `AUTH=PLAIN` and
`AUTH=LOGIN` will not be automatically included in
[imap_capabilities](#m-imap-capabilities).

<a id="index-1"></a>

<a id="m-imap-capabilities"></a>

### imap_capabilities

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_capabilities` extension ...;           |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

Sets the [IMAP protocol](https://datatracker.ietf.org/doc/html/rfc3501) extensions list that is passed to the client in response to the CAPABILITY command. The authentication methods specified in the [imap_auth](#m-imap-auth) directive and [STARTTLS](https://datatracker.ietf.org/doc/html/rfc2595) are automatically added to this list depending on the [starttls](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) directive value.

It makes sense to specify the extensions supported by the IMAP backends to which the clients are proxied (if these extensions are related to commands used after the authentication, when Angie transparently proxies a client connection to the backend).

<!-- The current list of standardized extensions is published at `www.iana.org <http://www.iana.org/assignments/imap4-capabilities>`_. -->

<a id="index-2"></a>

<a id="m-imap-client-buffer"></a>

### imap_client_buffer

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `imap_client_buffer` size;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `imap_client_buffer 4k|8k;`  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                 |

Sets the size of the buffer used for reading IMAP commands. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.