> For the complete documentation index, see [llms.txt](https://docs.aurinko.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurinko.io/authentication/configuring-imap-provider-connections-in-aurinko.md).

# Configuring IMAP Provider Connections in Aurinko

This guide explains how to configure Aurinko to work with IMAP email accounts, including provider credentials, server settings, synchronization, sending emails, and troubleshooting.

### What is IMAP?

***

**IMAP (Internet Message Access Protocol)** is a standard email protocol that allows email clients and applications to access and manage messages stored on a mail server while keeping them synchronized across multiple devices.

### Before You Start

***

Before connecting your IMAP account to Aurinko, you need:

* Your full email address
* An **app-specific password** or your regular email password, depending on your email provider
* Your IMAP server and port, if required by your provider
* Your SMTP server and port, if required by your provider

#### App-Specific Passwords

Most modern email providers require you to generate an **app-specific password** (also called an *application password* or *app password*) instead of using your regular account password.

App-specific passwords are credentials created specifically for third-party applications such as Aurinko. They provide an additional layer of security because you can:

* Revoke access without changing your main account password
* Limit access to a specific application
* Track which applications have access to your account

#### Where to Find App Password Settings

The exact process varies by email provider:

| Provider     | App Password Settings                                   |
| ------------ | ------------------------------------------------------- |
| **iCloud**   | Apple ID → Password & Security → App-Specific Passwords |
| **Yahoo**    | Account Security → App Passwords                        |
| **AOL**      | Account Security → App Passwords                        |
| **Zoho**     | Security → App-Specific Passwords                       |
| **Fastmail** | Settings → Privacy & Security → App Passwords           |

{% hint style="info" %}
**Note:** If your provider is not listed above, look for **App Passwords**, **Application Passwords**, or **Third-party App Access** in your account's security or privacy setting<br>
{% endhint %}

{% hint style="warning" %}
**Important:** **Save your app-specific password immediately.** Most providers display it only once and will not allow you to view it again later.
{% endhint %}

### Providers That Use Regular Passwords

***

Not all email providers support app-specific passwords. Some providers, typically smaller or self-hosted email services, may require you to use your regular email password for IMAP access.

These may include:

* Self-hosted IMAP servers
* Many custom-domain email hosting services
* Some legacy email providers

In these cases, enter your regular email password when connecting your account to Aurinko.

Once you have your credentials, you are ready to add your IMAP account to the Aurinko portal.

### Example: Generate a Gmail App Password

***

If you use Gmail and want to connect your account to Aurinko via IMAP, you may need to generate an app-specific password.

#### Step 1: Enable 2-Step Verification

Gmail app passwords can only be generated when **2-Step Verification** is enabled on your Google Account.

1. Sign in to your Gmail account.
2. Click your account icon in the top-right corner and select **Manage your Google Account**.
3. In the left-hand menu, select **Security**.
4. Under **How you sign in to Google**, find **2-Step Verification**.
5. If it is not enabled, click **Get started** and follow the on-screen instructions.

#### Step 2: Generate an App Password

After enabling 2-Step Verification:

1. Go to the **Security** section of your Google Account.
2. Under **How you sign in to Google**, select **App passwords**.
3. Enter your Google password again if prompted.
4. Under **Select app**, choose **Mail**.
5. Under **Select device**, choose the device you are using, or select **Other** and enter a custom name.
6. Click **Generate**.
7. Google displays a 16-character app password.

{% hint style="warning" %}
**Important:** **Copy the password immediately.** Google displays the generated password only once. The spaces displayed in the password are cosmetic and can be omitted when pasting it into Aurinko.
{% endhint %}

### Adding Your IMAP Account to the Aurinko Portal

***

Once you have your credentials, follow these steps to connect your account.

#### Step 1: Open the Aurinko Portal

Sign in to the [**Aurinko API Portal**](https://app.aurinko.io/) and go to **Accounts**.

#### Step 2: Add a New Account

1. Click **Add Account**.
2. Select **IMAP** from the list of service types.

{% hint style="info" %}
**Note for iCloud users:** iCloud has a dedicated service type in Aurinko. Select **iCloud** instead of **IMAP** to use the optimized integration for Apple's email services.
{% endhint %}

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2F5kxKkOwhNQUchAsNojhS%2FMonosnap%20Accounts%202026-09-22%2014-13-41.png?alt=media&amp;token=d94ab953-d982-4bb1-8e0c-2688cb9b0a4a" alt=""><figcaption></figcaption></figure>

#### Step 3: Select Scopes

Select the permissions your application requires.

| Scope         | Description                     |
| ------------- | ------------------------------- |
| **Read**      | Read emails and email metadata  |
| **ReadWrite** | Read, update, and delete emails |
| **Drafts**    | Create and manage drafts        |
| **Send**      | Send emails                     |

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FanmYXRd5IRnMKxeuUU7Z%2FMonosnap%20Accounts%202026-09-22%2014-11-37.png?alt=media&amp;token=41f0fa66-9cf5-45cb-bfcc-eb26a5a314f6" alt=""><figcaption></figcaption></figure>

#### Step 4: Enter Account Credentials

**Using a predefined provider?** You do not need to enter the IMAP or SMTP server details manually. Aurinko already has the required connection settings for supported providers.

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2F2Tpc0cQzmYFqIrs7VGuu%2FScreenshot%20at%20Sep%2022%2014-55-51.png?alt=media&amp;token=1480087c-d28a-4526-8de7-30f66b6cf1af" alt=""><figcaption></figcaption></figure>

**Using a custom or unsupported provider?** You will need to obtain the IMAP and SMTP server addresses and ports from your email provider's documentation or support team.

Enter your IMAP account information:

| Field                             | Description                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| **ServiceProvider**               | Select your email service provider                                                          |
| **Email**                         | Your full email address, for example `user@example.com`                                     |
| **Password**                      | Your app-specific password or regular email password                                        |
| **IMAP Server / Port (Incoming)** | The server address and port used for receiving emails. Required for custom email providers. |
| **SMTP Server / Port (Outgoing)** | The server address and port used for sending emails. Required for custom email providers.   |

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FWDOMVC9xyjwXeS9gJ80J%2FMonosnap%20Aurinko%20app%202026-09-22%2014-17-37.png?alt=media&amp;token=b060a7a3-954b-479f-8a84-6230776420d2" alt=""><figcaption></figcaption></figure>

### How Aurinko Connects to Your IMAP Server

***

Aurinko connects to your IMAP server using **IMAPS (`imaps://`)**, the secure, TLS-encrypted version of IMAP.

This ensures that communication between Aurinko and your mail server is encrypted.

Aurinko uses standard IMAP authentication methods, including:

* `PLAIN`
* `LOGIN`

These authentication methods are used over the encrypted IMAPS connection.

{% hint style="info" %}
**Security Note:** Your credentials are transmitted securely and are not stored in plain text. If you are unsure about your IMAP or SMTP server addresses, check your email provider's documentation or contact their support team. Incorrect server addresses or ports will prevent Aurinko from connecting to your account.
{% endhint %}

### Sending Emails and the "Sent Messages" Folder

***

#### How Aurinko Handles Sent Emails

When you send an email through the Aurinko API, Aurinko delivers the message to the recipient through your SMTP server.

However, not all email providers automatically save a copy of sent messages to the **Sent** folder.

For example:

* iCloud does not automatically add sent emails to the Sent Messages folder.
* Some self-hosted IMAP servers may also omit this step by default.

#### Enable Sent Email Copies

Aurinko provides an account-level option that allows sent emails to be copied to the **Sent Messages** folder.

To enable it:

1. Go to **Accounts**.
2. Select your IMAP account.
3. Find the **Copy sent emails to 'Sent Messages' folder** checkbox.
4. Turn the option **ON**.

After enabling this option, Aurinko automatically copies sent emails to the configured Sent folder.

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FMdUcWkL8XSNUZB5KT95F%2FMonosnap%20Accounts%202026-09-22%2014-20-32.png?alt=media&amp;token=0cc8779a-6ca9-4f88-84b7-2f71004e72b7" alt=""><figcaption></figcaption></figure>

### Account Creation and Background Synchronization

***

#### What Happens After You Submit the Form

After you submit the IMAP account configuration, Aurinko:

1. Creates the account and associates it with your application.
2. Starts a background synchronization process.
3. Continuously updates mailbox data, including:
   * Folder and directory structures
   * Email messages
   * Read/unread status
   * Other mailbox metadata

The background synchronization runs automatically. You do not need to manually trigger updates.

#### Initial Synchronization

During the initial synchronization, Aurinko performs a full scan of your mailbox to build an index of folders and messages.

Depending on the size of your mailbox, the initial synchronization may take some time.

### Troubleshooting

***

If Aurinko encounters an issue while connecting to or synchronizing your IMAP account, the error details are displayed on the account page.

#### View Provider Errors

1. Go to **Accounts**.
2. Select your IMAP account.
3. Open the **Provider Errors** section.

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FGKliaiLzY6BSQEeuBQoh%2FMonosnap%20Accounts%202026-09-22%2014-22-39.png?alt=media&amp;token=6f467855-8249-47b2-ad87-33bcd68bf0e4" alt=""><figcaption></figcaption></figure>

Common provider errors include:

* Authentication failures caused by an incorrect password or app-specific password
* Server connection timeouts
* SSL/TLS handshake errors
* Rate limiting
* Server bans or connection restrictions

#### Need Help?

If you see an error in **Provider Errors** that you do not understand, or the problem persists after verifying your credentials and server settings, contact Aurinko Support.

Include the following information:

* Your account ID
* The exact error message shown in **Provider Errors**
* Your email provider
* Relevant timestamps

This information will help the support team diagnose and resolve the issue more quickly.

### Using Your IMAP Account with the Unified Email API

***

Once your IMAP account has been successfully added and synchronized, you can interact with it through the **Aurinko Unified Email API**.

The REST API provides a consistent interface for accessing and managing email across supported providers, including:

* Google
* Microsoft 365
* iCloud
* IMAP

#### Key Capabilities

The Email API allows you to:

* Read email messages, including content, sender and recipient information, subject lines, and dates
* Search inboxes using the `q` parameter
* Update message status, including read/unread and flagged status
* Manage and download email attachments
* Create drafts and send emails
* Perform incremental synchronization to efficiently retrieve only changes

### Full Documentation

For the complete API reference, including endpoints, parameters, and response formats, see the [**Aurinko Email API Documentation**](https://docs.aurinko.io/unified-apis/email-api).