> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/email.md).
# Connect a Conversation Platform: Email
Connect the Email channel: set up the mailbox account for receiving and sending (Gmail requires an app-specific password), bind an Agent, and let the Agent reply automatically to incoming emails — ste
## Before You Connect
* An "AI Assistant" has been created on the [MaiAgent platform](https://admin.maiagent.ai/)
* The email account to connect is ready (Gmail, Outlook, Yahoo, or a custom mail server)
* If you use Gmail or Outlook, generate an **app-specific password** first (not your account password)
{% hint style="warning" %}
Gmail requires a 16-digit app-specific password; you cannot sign in with your Google account password. Generate one at [Google Account Security](https://myaccount.google.com/apppasswords) first.
{% endhint %}
## What the Email Channel Does and Doesn't Do
The Email channel works as "receive an email → the Agent replies automatically": MaiAgent uses IMAP to fetch new emails sent to this mailbox, hands them to the bound Agent to generate a reply, and then replies to the sender over SMTP. Every incoming email and reply appears in All Conversations, where support staff can also take over the reply. It does not import existing emails from the mailbox, and users cannot search or query the contents of this mailbox from a conversation.
To search email, summarize messages, or draft replies in a conversation, use MaiGPT [Connectors](/maiagent-user-guide/en/work/maigpt/connectors.md) to connect Google Workspace (Gmail) or Microsoft 365 (Outlook). Available connectors depend on your organization's connector menu.
## Start Connecting
### 1. Go to the Connect Channel Page
Click Channels in the left menu, then click the Connect Channel button in the upper right corner.
### 2. Select Email
On the platform selection page, click Email.
### 3. Select the Email Provider
Choose from the Email Provider dropdown:
| Provider | Description |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| **Gmail** | Google mailbox; requires an app-specific password |
| **Outlook / Office 365** | Microsoft mailbox; requires an app-specific password when two-step verification is enabled |
| **Yahoo Mail** | Yahoo mailbox; requires an app-specific password |
| **Custom** | Configure the IMAP/SMTP server parameters yourself |
After you select a provider, the system automatically fills in the corresponding IMAP and SMTP server settings.
### 4. Enter Connection Information
#### Email Address
Enter the full email address to connect, for example `support@yourcompany.com`.
#### IMAP Settings (Receiving)
| Field | Description |
| --------------- | --------------------------------------------------------- |
| **IMAP Server** | Incoming mail server address (`imap.gmail.com` for Gmail) |
| **IMAP Port** | Port number (usually 993) |
| **Use SSL** | Recommended, to keep transmission secure |
#### SMTP Settings (Sending)
| Field | Description |
| --------------- | --------------------------------------------------------- |
| **SMTP Server** | Outgoing mail server address (`smtp.gmail.com` for Gmail) |
| **SMTP Port** | Port number (usually 587) |
| **Use TLS** | Recommended, to keep transmission secure |
#### Authentication
| Field | Description |
| ------------ | ------------------------------------------------- |
| **Username** | Usually the email address |
| **Password** | App-specific password (not your account password) |
### 5. Test the Connection
After filling in the fields, click the Test Connection button. The system tests both the IMAP (receiving) and SMTP (sending) connections.
* **Connection succeeded**: shows "Connection successful! IMAP and SMTP server connection tests passed"
* **Connection failed**: the system shows the specific error (authentication failure, server unreachable, etc.); correct the settings accordingly
{% hint style="danger" %}
Always complete the connection test before saving, and confirm that both IMAP and SMTP connect successfully.
{% endhint %}
### 6. Basic Settings and Save
| Field | Description |
| -------------------- | ------------------------------------------------------------------ |
| **Channel Name** | A name for this connection |
| **AI Assistant** | Select the Agent to bind |
| **Polling Interval** | (Optional) How often the system checks for new emails (in seconds) |
| **Reset Command** | (Optional) A command that lets users start the conversation over |
After confirming the settings, click Save to finish connecting.
Once connected, when someone sends an email to that address, the Agent automatically reads the email and replies.
{% hint style="info" %}
After a successful connection, you can find it in the channel list. Click Edit to configure further options (scheduled replies, sender-name awareness, permission control, and more).
{% endhint %}
## How Incoming Attachments Are Handled
Attachments in incoming emails (including inline images in the HTML body) are saved as attachments of that message and are handled the same way as files a user uploads in Web Chat:
| Attachment type | How the Agent reads it |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Images (`.png`, `.jpg`, `.gif`, `.webp`, etc.) | Passed directly to the Agent's language model for interpretation, so the Agent must use a multimodal model; turn on Enable OCR in the feature settings to recognize text in images |
| Documents (PDF, Word, Excel, CSV, PowerPoint, TXT, and other formats supported by the knowledge base) and audio | **The Agent must use Agent mode**: based on the email, the Agent decides whether to use the attachment tools to parse the file, read the full text, or build an index, and then replies accordingly. Excel/CSV files are converted to table text so the Agent can answer questions about cell values, and audio is first converted to a transcript. Other reply modes only keep the attachment file, and the Agent cannot read its content |
* Parsing happens when the Agent replies, so the first reply may be slower when there are many attachments or the files are large. Parsing costs are charged to Credits according to the knowledge base's parser rules.
* Attachments belong only to that conversation and do not enter the knowledge base. Retention follows the platform's attachment cleanup settings; once expired, the attachments and their parsed copies are deleted automatically. See [Credits Billing System](/maiagent-user-guide/en/others/credits.md#attachment-and-derived-storage).
* The attachment tools can be turned off individually in the Agent's advanced settings; see [Configure Tools for an Agent](/maiagent-user-guide/en/build/tools/configure_tools.md). For processing details, see [Technical Manual - How Message Attachments Are Processed](https://docs.maiagent.ai/tech/api-integration/api_knowledge#attachment-processing).
## Can Email Content Be Exported?
The Email channel has no "export to PDF/Excel" feature, and the Agent does not convert incoming email content into files. Incoming emails and replies both become conversation records, which you can view in [All Conversations](/maiagent-user-guide/en/serve/daily-operations/reply.md), or filter in [Agent Monitoring](/maiagent-user-guide/en/build/agent-ops/evaluations.md) and export in batches to Excel (see [Conversation Viewer: Batch Export](/maiagent-user-guide/en/serve/daily-operations/reply/conversation-viewer.md#batch-export)). To turn the content of a single email into a document, ask the Agent to produce it with [Canvas](/maiagent-user-guide/en/work/maigpt/canvas.md#export) and then download it.
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/email.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.