Skip to content
Build Perch
Browse documentation

Gmail

Short answer: Build Perch connects to email through a dedicated Gmail mailbox, authenticated with a Google app password over IMAP and SMTP, not OAuth into your everyday inbox. Every outgoing message stops at your approval before it sends.

How does the Gmail integration work?

Build Perch connects directly to Gmail’s servers over IMAP (for reading) and SMTP (for sending). Authentication is a 16-character Google app password rather than an OAuth grant: no third-party consent screen, and app passwords keep working on an account with 2-Step Verification on. Because a password-based connection is coarser than a scoped OAuth grant, Build Perch is built around connecting a dedicated mailbox (one made for this purpose, that you feed by forwarding mail in) rather than your everyday personal inbox.

Only Gmail addresses work. The app connects only to imap.gmail.com / smtp.gmail.com, and any other address is rejected. Outlook.com is intentionally excluded: Microsoft removed app-password IMAP access for it.

How do I connect a mailbox?

  1. Pick or create the Gmail address you want to dedicate to this: somewhere you forward mail to, not your main inbox.
  2. On that account, turn on 2-Step Verification, then go to Google Account → Security → App passwords and generate a 16-character app password.
  3. In Build Perch, open Integrations and expand the Gmail row.
  4. Paste the address and the app password, and click Save.
  5. Click Test connection; on success it reports how many messages are in INBOX.
  6. Add the Email skill to a mode (or the current chat) so the AI can actually use it; like every integration, it’s off until you opt it in.

What can the AI do with it?

  • List and search the mailbox’s INBOX: email_list_messages and email_search return sender, subject, date, and unread status.
  • Read a full message: email_get_message returns the body plus a list of attachments.
  • Download an attachment into the workspace with email_get_attachment, so the file tools can open or edit it.
  • Send a new message or reply in-thread: email_send and email_reply can attach workspace files, and both stop at an approval banner showing the recipient, subject, and body before anything goes out.

Reads only cover the connected mailbox’s INBOX, not other folders or labels.

Good to know

  • The app password is stored in the OS-native credential vault and is write-only from the app’s side: once saved, the interface can replace or delete it, but never read it back.
  • Sending can’t skip approval. email_send and email_reply are flagged as external sends; they never auto-approve, even with auto-approval set to “approve everything.”
  • A dedicated mailbox scopes what the AI (and the app password) can ever touch to mail you’ve deliberately routed there.