> For the complete documentation index, see [llms.txt](https://help.refractbot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.refractbot.com/misc./imap.md).

# IMAP

IMAP lets Refract read one-time codes from your email and submit them automatically, speeding up logins and checkouts on sites like Best Buy.

Some sites email you a one-time code during login or checkout. With an IMAP login added, Refract reads the code from your inbox and submits it automatically instead of making you race to type it in. Best Buy email codes and Target OTP login both rely on this.

IMAP logins live in the bot under **Settings > IMAP Logins**.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-96816d8fc99bc5b353a62a8a506ab893fe0d1c65%2Fimap-settings-tabs.png?alt=media" alt="The IMAP Logins tab in bot Settings"><figcaption><p>The IMAP Logins tab, with the toolbar in the top right.</p></figcaption></figure>

{% hint style="warning" %}
**Outlook emails are not supported.** The only way to use an Outlook email with Refract is through AYCD Inbox. See the AYCD Inbox section below.
{% endhint %}

## Add an IMAP login

{% stepper %}
{% step %}

#### Create a login

On the **IMAP Logins** tab, click the **+** (Create Login) button.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-010cd9e9d3dc2fe4d6f384cc9fe85f143acdb495%2Fimap-toolbar.png?alt=media" alt="The IMAP toolbar buttons" width="416"><figcaption><p>Left to right: AYCD, Create Login, Export Logins, Login Selected, Delete.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Choose your server

Pick your email provider from the **Server** dropdown: **Gmail**, **iCloud**, **Yahoo**, or **Custom** for any other IMAP provider.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-98e11409fa5f5097e94749bc9b8bd5908e2bc515%2Fimap-add-login.png?alt=media" alt="The Add IMAP Login window" width="450"><figcaption><p>Pick the server, then add one login or switch to Mass login input.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Enter your credentials

For a single account, use **Input one login** and enter the username and password. To add many at once, switch to **Mass login input** and paste credentials one per line in `username:password` format.

The password is usually not your normal email password. Gmail, iCloud, and Yahoo all require an app password for IMAP; see the section below for how to generate one.
{% endstep %}

{% step %}

#### Create the login

Click **Create Login**. Your account appears in the list, ready to pull codes.
{% endstep %}
{% endstepper %}

## Get an app password

Follow the section for your provider, then use the generated app password as the password in Refract.

{% hint style="warning" %}
**Treat app passwords like real passwords.** Anyone with one can read your email over IMAP. If one is ever compromised, delete it with your provider and create a new IMAP login in Refract.
{% endhint %}

### Gmail

1. IMAP is enabled by default on all Gmail accounts.
2. Enable 2FA at [myaccount.google.com/signinoptions/two-step-verification/enroll-welcome](https://myaccount.google.com/signinoptions/two-step-verification/enroll-welcome). App passwords require it.
3. Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords), add a custom app name like `Refract`, and click create. Use the generated password in Refract.

{% hint style="warning" %}
**Gmail limits simultaneous IMAP connections.** Google documents the limit as 15 connections per account, but in practice it kicks in sooner. Avoid using the same IMAP login in multiple bots at the same time. If you hit the limit, the only fix is to close the other connections, wait, and then log in again.
{% endhint %}

### iCloud

1. Sign in at [account.apple.com](https://account.apple.com).
2. Open **Sign-In and Security > App-Specific Passwords**.
3. Generate a new password with a name like `Refract` and use it in Refract.

### Yahoo

1. Go to [login.yahoo.com/myaccount/security](https://login.yahoo.com/myaccount/security).
2. Scroll down to **Other ways to sign in**.
3. Click **Generate app password** and generate a new one.
4. Use the generated app password to add your Yahoo account in Refract.

### AOL

1. Go to [login.aol.com/myaccount/security](https://login.aol.com/myaccount/security/).
2. Scroll down to **Other ways to sign in**.
3. Click **Generate app password** and generate a new one.
4. Add the account in Refract using the **Custom** server option with your AOL address and the app password.

## AYCD Inbox

Refract integrates with [AYCD Inbox](https://support.aycd.io/account/guides/category/inbox), an email client built for managing large numbers of accounts. If you run your emails through Inbox, Refract can pull codes from it directly. This is also the only way to use Outlook emails with Refract.

{% hint style="success" %}
**Refract users get an AYCD partnership discount.** Claim it here: [aycd.io/account/partnership/offers](https://aycd.io/account/partnership/offers?guild=1509889256590676110)
{% endhint %}

{% hint style="danger" %}
**AYCD has to be open and running.** The Inbox API only works while the AYCD application is running with Inbox active on the same machine as Refract. Close AYCD and Refract stops receiving codes, even though the API key is still saved. Leave it open for the whole drop.
{% endhint %}

{% hint style="info" %}
**AYCD Inbox does not replace your IMAP logins.** You can have both in use at the same time. A common setup is Outlook accounts through Inbox and every other email as a regular IMAP login.
{% endhint %}

{% stepper %}
{% step %}

#### Open the AYCD configuration

On the **IMAP Logins** tab, click the **AYCD** button.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-92b9205dfea280d54cce083e7fb0a6f5646574b3%2Fimap-aycd.png?alt=media" alt="The Configure AYCD Inbox window" width="420"><figcaption><p>Paste your Inbox API key. Template ID usually stays Default.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Paste your API key

Enter your Inbox API key. It starts with `Inbox-`.
{% endstep %}

{% step %}

#### Set the Template ID

Usually leave this as **Default**. It only matters if you use forwarding or catchall setups in Inbox.
{% endstep %}

{% step %}

#### Save

Click **Save**. Refract now pulls codes through AYCD Inbox.
{% endstep %}
{% endstepper %}

Setting up Inbox itself (adding your accounts, OAuth2 logins, forwarding) is covered by AYCD's own guides: [support.aycd.io/account/guides/category/inbox](https://support.aycd.io/account/guides/category/inbox).

## Manage your logins

* **Right-click a login** to **Edit**, **Login**, or **Delete** it.
* **Login Selected** (the lock button) logs the selected accounts into their mail servers.
* **Export Logins** exports your saved logins.
* The red **X** deletes the selected logins.

## Connection status and errors

The **Status** column tells you whether each login is working. A working login shows **Connected** in green. That is what you want to see before a drop.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-6d12e6fb4055f743004f3d1e078aa5cff612d1b9%2Fimap-status-connected.png?alt=media" alt="IMAP logins showing green Connected status"><figcaption><p>Green Connected means the login is working.</p></figcaption></figure>

If a login has a problem, the status shows a red error in the form `Error: <error code>`. The most common one:

* **Error: Invalid credentials (Failure):** the email or password is wrong. Remember the password usually needs to be an app password, not your normal email password. Edit the login (right-click > **Edit**) and fix the credentials.

<figure><img src="https://2861066425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjdmk3RduT9OdU2B3zFmG%2Fuploads%2Fgit-blob-605eb5611871e8871346a176c2989ea037c8af7d%2Fimap-error-invalid-credentials.png?alt=media" alt="An IMAP login showing Error: Invalid credentials (Failure)"><figcaption><p>Invalid credentials: the email or password is wrong. Usually it needs an app password.</p></figcaption></figure>

If a previously working login starts erroring, check whether that same email is connected somewhere else. Providers limit simultaneous IMAP connections, so the same login running in several bots at once will get rejected. Close the other connections, wait, then log in again.

## FAQ

<details>

<summary>Is there an AYCD discount for Refract users?</summary>

Yes. Claim the partnership offer here: [aycd.io/account/partnership/offers](https://aycd.io/account/partnership/offers?guild=1509889256590676110)

</details>

<details>

<summary>Does AYCD need to be open for Inbox to work?</summary>

Yes. AYCD has to be running with Inbox active on the same machine as Refract for the whole time you need codes. The Inbox API pulls codes through the running AYCD application, so closing it stops codes arriving even though your API key is still saved in Refract.

</details>

<details>

<summary>Can I use both IMAP logins and AYCD Inbox at the same time?</summary>

Yes. Both can be in use at the same time; connecting AYCD Inbox does not disable your IMAP logins. A common setup is Outlook accounts through Inbox and every other email as a regular IMAP login.

</details>

<details>

<summary>Why is my IMAP not submitting the codes?</summary>

* The code may never have been sent in the first place. Sites like Best Buy are notorious for making tasks wait for a code that never comes.
* If the code was sent, make sure it lands in the **Inbox** folder of your email. If your mail rules sort it into another folder, Refract may not be able to find it.
* Check your device time (below). If it is out of sync, IMAP will not work.
* If you pull codes through AYCD Inbox, check that AYCD is actually open and running. Codes stop arriving the moment it is closed.

</details>

<details>

<summary>Fix your device time (IMAP will not work if it is wrong)</summary>

Your device time must be in sync with your local time.

On Windows:

1. Press **Win + I** to open Settings.
2. Go to **Time & Language > Date & time**.
3. Toggle **Set time automatically** and **Set time zone automatically** ON.
4. Click **Sync now** under Additional settings. If there is no Sync now button, turn both toggles off and back on to force a sync.
5. If the time zone is wrong, turn off **Set time zone automatically** and pick the correct zone from the dropdown.

On Mac:

1. Open the Apple menu and choose **System Settings**.
2. Go to **General > Date & Time**.
3. Toggle **Set time and date automatically** ON.
4. Click **Time Zone** and make sure **Set time zone automatically** is enabled.
5. If changes do not apply, restart your Mac.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.refractbot.com/misc./imap.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.