Connect Email (IMAP / Other email)

This guide walks you through connecting a mailbox to Pinchy using standard IMAP (for reading) and SMTP (for sending) — the protocol almost every email provider supports. Use this when your provider isn't Gmail or Microsoft 365: Fastmail, iCloud, GMX, Zoho, a company mail server, or anything you self-host.

Unlike Google and Microsoft, there's no OAuth app to register first. You connect a mailbox directly with its server settings and a password — one step, no separate "app" to manage.

Prerequisites

• You're logged in as an admin in Pinchy
• Your email address
• An app-specific password, if your provider supports one

Caution

Use an app-specific password if your provider offers one. Many providers — Fastmail, iCloud, GMX, Yahoo, and others — require a separate app password instead of your regular account password once two-factor authentication is turned on. Using your regular password will fail the connection test. Look for "app passwords" or "app-specific passwords" in your provider's account security settings and generate one for Pinchy.

You'll also need your IMAP and SMTP server hostnames and ports — but Pinchy tries to fill these in for you automatically, so you often don't need to look them up.

Connect the account in Pinchy

1. Open the Add Integration wizard

   In Pinchy, go to Settings → Integrations, click Add Integration, then select IMAP / Other email.

2. Enter your details

   Three fields are all most mailboxes need:

   • Your name (optional) — shown to recipients when an agent sends email from this mailbox (Clemens Helm <clemens@example.com> instead of a bare address).
   • Email address — when you tab away from this field, Pinchy looks up your provider's server settings automatically (via its built-in provider list and your domain's DNS records).
   • Password — use an app-specific password if your provider requires one (see the caution above).

3. Check the server settings

   If Pinchy found your provider's settings, they appear as a one-line summary — you don't need to touch them. Click Edit server settings if you want to inspect or change them.

   If your provider wasn't recognized, the server fields open up pre-filled with a best guess. Verify them against your provider's documentation:

   • IMAP host and IMAP port — usually port 993
   • SMTP host and SMTP port — usually port 465 or 587
   • Username — pre-filled with your email address, which is what almost every provider expects
   • Security — leave on Automatic (TLS); Pinchy picks implicit TLS or STARTTLS based on the port. None disables encryption entirely and is only for special setups like a local Proton Mail Bridge.

   Your provider's help pages usually list these under "IMAP/SMTP settings" or "set up a mail client." Search for <your provider> IMAP settings if you're not sure.

4. Test & Save

   Click Test & Save. Pinchy logs in to both the IMAP and SMTP servers and, if both succeed, saves the connection in one step — a broken connection can't end up saved and silently unusable.

   If the test fails, the server settings open up with a specific failure reason — wrong credentials, unreachable host, or a TLS mismatch — so you can correct them and try again.

   The mailbox then appears in the Integrations list, named after its email address (rename it anytime from the list), ready to grant to agents.

Reading messages across folders

Note

Listing, searching, reading, and downloading attachments all work across folders (INBOX, SENT, DRAFTS, TRASH, SPAM). IMAP message IDs are only unique within a single mailbox, so the ID that email_list and email_search return carries its source folder with it — email_read and email_get_attachment then open the right mailbox automatically. An agent can find a message in any folder and open it directly.

Note

Sent mail is filed to your Sent folder. When an agent sends email over SMTP, Pinchy also files a copy into the mailbox's Sent folder over IMAP (a best-effort archive), so sent messages show up in your mail client and in email_search({ folder: "SENT" }).

Grant agent email permissions

A connection alone doesn't give any agent access. You must explicitly grant permissions per agent — the same model used for Gmail and Microsoft 365.

Note

Only shared agents have a Permissions tab. Personal agents can't be granted integration access — email permissions are a shared-agent feature.

1. Open the agent you want to connect to email

2. Click the gear icon to open Agent Settings

3. Select the Permissions tab

4. In the Email section, select the connected account and check the operations this agent may perform:

   • Read messages — list, read, and search emails
   • Create drafts — create draft emails (saved but not sent)
   • Send messages — send emails immediately (cannot be undone)

5. Click Save & Restart and confirm. Permission changes restart the agent runtime, so active chats are briefly disconnected.

Caution

Send messages is a powerful permission. The agent can send email from the connected account without human review. Consider using Create drafts instead — a human reviews and sends drafts manually.

---

Test it

Open the agent's chat and try a few queries:

• "Show me my latest unread emails"
• "Search for emails from max@example.com about invoices"
• "Draft a reply to the last email saying we'll process it today"
• "How many unread emails do I have?"

---

Available tools

When email permissions are granted, the agent gets access to these tools — the same set used for Gmail and Microsoft 365:

Tool	Permission required	Description
email_list	Read	List emails from a folder (INBOX, SENT, DRAFTS, TRASH, SPAM; defaults to INBOX). Supports filtering by read status.
email_read	Read	Read the full content of a specific email by ID. Lists any attachments with their IDs. Looks up the message in INBOX (see the limitation above).
email_get_attachment	Read	Download an email attachment into the agent's workspace. Looks up the message in INBOX (see the limitation above).
email_search	Read	Search emails using structured fields: from, to, subject, text, unread, sinceDays, folder, limit (e.g. { from: "user@example.com", subject: "invoice", sinceDays: 7 }).
email_draft	Draft	Create a draft email. Saved directly to the mailbox's Drafts folder over IMAP.
email_send	Send	Send an email immediately over SMTP. Can also send replies with replyTo.

---

Troubleshooting

"Authentication failed — check the username and password"

The most common cause is using your regular account password instead of an app-specific password on a provider that requires one. Generate an app password in your provider's account settings and use that instead.

"Could not connect to the server — check the host and port"

The IMAP or SMTP host is unreachable — a typo in the hostname, a firewall blocking the port, or a provider that uses non-standard ports. Double-check the values against your provider's documented IMAP/SMTP settings.

"Could not establish a secure connection — check the security setting"

The Security setting doesn't match what the server expects. Try TLS for port 993 (IMAP) or 465 (SMTP submission), and STARTTLS for port 587.

"Connection timed out — check the host and port"

The server didn't respond in time — usually a network issue or an incorrect host/port combination.

"Blocked: this host resolves to a private network address"

See Mail servers on your own network below.

---

Mail servers on your own network

The connection test reports exactly why an attempt failed — refused, timed out, TLS error, wrong password. That's what makes it useful for fixing a mailbox, and it's also what would make it useful for mapping the network Pinchy runs in. So we only probe hosts that resolve to a public address.

If your mail server genuinely lives on your own network — an on-premise Exchange or Dovecot box on 10.x, 172.16–31.x, 192.168.x, or an IPv6 unique-local range — set the environment variable on the Pinchy container and restart it:

ALLOW_PRIVATE_MAIL_HOSTS=1

Loopback and link-local addresses stay blocked either way — 127.0.0.1, ::1, 169.254.169.254 and fd00:ec2::254, the cloud metadata endpoints. No mail server lives there, so there's nothing to trade off.

The same check runs when the connection is saved, not only when it's tested, so a blocked host can't be stored and quietly reconnected to later by an inbox sweep.

---

Ports, TLS & cloud firewalls

Pinchy runs the connection test from the exact server that will send your mail — so if the SMTP leg times out or gets refused, that's real evidence about what this server can reach, not a guess. We use it: on a connection timeout or refusal, we also probe the standard SMTP ports (465, 587, 25) directly from the container, and if a different port is reachable, we show a banner with a one-click "Switch & retry" button for it. Click it and we update the SMTP port and security setting for you and re-run the test — nothing switches silently.

Note

This only ever happens for connection-level failures (timeout or refused). An authentication or TLS/certificate failure never triggers a port probe — those aren't firewall problems, so a different port wouldn't fix them.

Why cloud hosts block SMTP ports

Cloud providers block outbound mail ports by default on new servers — it's an anti-spam measure, not a Pinchy limitation. The exact ports blocked vary by provider:

Provider	Blocked outbound	Open	Unblocking
Hetzner	25, 465	587	Usually opens automatically after ~1 month of account age, or via a support ticket
DigitalOcean	25, 465, 587	none by default	Open a support ticket requesting outbound mail ports be unblocked
AWS / GCP / Azure	25	465, 587	Port 25 stays blocked by policy; use 465 or 587 instead

Port 587 (STARTTLS submission) is the safest default for a new cloud server — it's the one port most providers leave open. Port 465 (implicit TLS) is the next most likely to work. Port 25 (unencrypted SMTP relay) is blocked almost everywhere and isn't worth troubleshooting for outbound mail.

Testing reachability yourself

You can check the same thing Pinchy's probe checks, directly from the server (or a shell on the same host):

# Raw TCP reachability (no TLS, no auth) — mirrors what Pinchy's probe does
nc -vz smtp.example.com 587

# Full TLS handshake against an implicit-TLS port (465)
openssl s_client -connect smtp.example.com:465

nc reporting "succeeded" (or openssl reaching a certificate dump instead of hanging) means the port is reachable from this server. A hang followed by nothing means it's filtered — usually the host's outbound firewall, not your mail provider.

Requesting an unblock

If every standard port is blocked (Pinchy's "all outbound SMTP ports appear blocked" banner), the fix has to happen at the host level:

• Hetzner: open a support ticket asking to unblock outbound SMTP for your server/project. New accounts are usually auto-unblocked after roughly a month of account age.
• DigitalOcean: open a support ticket from the control panel requesting outbound mail ports be enabled for your account.
• AWS / GCP / Azure: port 25 is blocked by long-standing policy and generally isn't unblocked on request — use port 465 or 587 instead, which these providers leave open.

---

What's next

• Connect Email — overview and comparing Gmail, Microsoft 365, and IMAP
• Integrations — how connections and permissions work
• Agent Permissions — the full allow-list model