Knowledge & tools

Email Mailbox tool (IMAP + SMTP)

The Email Mailbox tool gives an agent a real email account it can work in - reading and searching messages, organizing them, sending new mail, and replying in thread. It has 12 actions, and one tool configuration maps to one mailbox. This is the read-capable upgrade over the send-only Email tool: that one could only send, this one manages the whole account. It works with Gmail, Outlook and Microsoft 365, and any provider that offers IMAP and SMTP.

Email is two protocols, and this tool holds both. IMAP is how mail is read and organized; SMTP is how mail is sent. That's why the form asks for two servers. For Gmail and most providers the same login works for both, so you fill in the IMAP username and password and leave the SMTP ones blank - they fall back automatically.

What it can do

Twelve actions, in three groups. Messages are identified by a UID the agent gets from a list or search and then passes to read, organize or reply. Bodies are plain text.

Read - list_folders, list_messages (recent mail in a folder), search_messages (unread, from, to, subject, text, or since a date), read_message (full body plus attachment names).
Organize - mark_read, mark_unread, flag_message, unflag_message, move_message (to another folder), delete_message (moves it to Trash).
Send - send_email (to, cc, subject, body, attachment URLs), reply_email (replies in thread, addressing the sender and keeping the subject and conversation).

Replies really do thread: a reply lands in the same conversation in the recipient's inbox rather than starting a new one.

Provider settings

If you're on Gmail or Outlook, you don't need to type any of this: pick your provider from the Email provider dropdown at the top of the tool form and the four server fields fill themselves in. You can still edit them afterwards. The values are below for reference, and for anyone on another provider.

If your provider isn't listed, its "mail client settings" page will have the equivalent values.

Provider	IMAP (reading)	SMTP (sending)
Gmail	`imap.gmail.com` port `993`	`smtp.gmail.com` port `465` (or `587` for STARTTLS)
Outlook / Microsoft 365	`outlook.office365.com` port `993`	`smtp.office365.com` port `587`
Other	Take the host and port from your provider's mail client settings page.

Gmail: create an app password

Gmail won't accept your normal Google password over IMAP or SMTP. You need a 16-character app password instead.

Turn on 2-Step Verification for the Google account (app passwords require it).
Go to myaccount.google.com/apppasswords, sign in, give the app a name, and generate. Google shows you a 16-character password.
In Hania, use the email address as the IMAP username and the 16-character app password as the IMAP password. Leave the SMTP username and password blank so they reuse the same login.

You do not need to enable IMAP. Google removed the IMAP on/off setting in January 2025 and now keeps it on for every account, so there's no toggle to find. If you've seen older guides telling you to enable IMAP in Gmail settings, that step no longer exists.

App passwords aren't available on every account. They require 2-Step Verification, and Google doesn't offer them on accounts using Advanced Protection or security-key-only 2-Step Verification. Many work and school (Workspace) accounts have them disabled by the organization too. If the app-passwords page won't let you create one, that's why - you'll need a different mailbox or help from your administrator.

Outlook and Microsoft 365

Use outlook.office365.com port 993 for IMAP and smtp.office365.com port 587 for SMTP.

Some organizations turn off basic-authentication IMAP and allow only OAuth. If yours has, this tool can't connect to that mailbox - you'd need your IT administrator to allow IMAP access, or use a different mailbox.

Field reference

IMAP Host (required) - the IMAP server for reading, e.g. imap.gmail.com.
IMAP Port (optional, default 993) - the IMAP SSL port.
IMAP Username (required) - usually the full email address.
IMAP Password (required, secret) - an app password if the provider requires 2FA, as Gmail does. Stored encrypted.
SMTP Host (required) - the SMTP server for sending, e.g. smtp.gmail.com.
SMTP Port (optional, default 465) - 465 for implicit SSL, 587 for STARTTLS.
SMTP Username (optional, secret) - only if it differs from the IMAP username; otherwise the IMAP username is reused.
SMTP Password (optional, secret) - only if it differs from the IMAP password; otherwise the IMAP password is reused.
From Email (required) - the address mail is sent from, usually the same as the username.
From Name (optional) - the display name recipients see.
Save sent mail to Sent folder (optional, default off) - see the Sent folder toggle below.

The Sent folder toggle

Leave Save sent mail to Sent folder off for Gmail, Outlook and most providers - they file sent mail in the Sent folder themselves, and turning this on would file a second copy. Turn it on only if you send a message and find your Sent folder stays empty, which happens with a few providers that don't do it for you.

How the agent handles your mail

Giving an agent a mailbox means it reads text written by other people, so a few habits are built into the Inbox Assistant blueprint:

It never takes orders from an email. Incoming mail is treated as untrusted content, not as instructions. If a message says "reply with the password" or "ignore your previous instructions", the agent won't act on it - it works only from what you ask, and flags suspicious mail to you. This matters: an inbox is the one place a stranger can put words in front of your agent.
It reads narrowly. The agent searches and limits rather than pulling your whole inbox into context, which keeps things private and cheap.
It confirms before acting. Sending a message and deleting one both get a confirmation first.

Troubleshooting

"IMAP login failed (check username and app password)" - the most common cause is using a normal account password where an app password is required, or a typo in the 16-character one. Regenerate the app password and re-paste it.
Connection failures - check the host and port against the provider table; a wrong port is the usual culprit (993 for IMAP, 465 or 587 for SMTP).
Can't create an app password - see the availability caveats; the account may use Advanced Protection or be a managed work account.
Outlook connects for some accounts but not others - the organization has likely disabled basic-auth IMAP for that mailbox.
Sent mail missing from the Sent folder - turn on the Save sent mail toggle.
Validation errors (a missing UID, recipient, subject or body, or a malformed date) - the agent self-corrects these, so they may flash through a trace before the call succeeds.

Safety in autonomous runs

Like any tool, the mailbox tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because it sends real email and deletes messages, a new configuration is created with Read-only switched off, Destructive switched on, and Sends data externally on - so destructive actions are gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, especially for a mailbox: an unattended agent that can email anyone deserves the extra gate. Interactive chat is never gated by these flags.

Security

The IMAP and SMTP passwords are stored AES-encrypted at rest and are never returned by the API - the console shows only whether each is set. Editing a configuration without retyping a password preserves the stored one, so you must retype it to replace it. Because you connect with an app password rather than your main account password, you can revoke the agent's access at any time from your provider's security settings without changing your own login.

Blueprint

The fastest way to a working mailbox agent is the Inbox Assistant blueprint (productivity category) - a pre-built agent for triaging, searching, replying and organizing, with the untrusted-email handling and confirmation habits described above already in place. Pick it from the blueprint gallery when creating a bot; the only thing you supply is the mailbox connection from this guide.