Check Email

Read recent emails from a Gmail inbox via IMAP. Returns text with subject, sender, date, and body per email. Read-only — never marks messages as read.

bdambrosio 58ea126 3 files · 20.9 KB Updated

File contents

check-email

Read emails from Gmail using IMAP. Newest first. Connects via SSL to imap.gmail.com:993, opens folders in read-only mode (no side effects on the mailbox).

Required environment

  • GMAIL_ADDRESS — Gmail address (IMAP username)
  • GMAIL_APP_PASSWORD — 16-character App Password from Google Account → Security → App Passwords

Without both, the tool returns an error and no data.

Gmail folder names

Folder IMAP name
Inbox INBOX
Sent [Gmail]/Sent Mail
Drafts [Gmail]/Drafts
All Mail [Gmail]/All Mail
Starred [Gmail]/Starred
Important [Gmail]/Important

Examples

{"thought": "check the last 5 inbox emails", "tool": "check-email", "limit": 5}
{"thought": "find unread emails about the quarterly report", "tool": "check-email", "query": "quarterly report", "unseen_only": "true"}
{"thought": "emails from boss this month", "tool": "check-email", "from_addr": "boss@company.com", "since": "2026-05-01"}

Notes

  • Email body is capped at 50,000 characters per message.
  • Body prefers plain text; HTML is tag-stripped as fallback.

bdambrosio/cognitive_workbench/tree/main/src/tools/check-email commit 58ea126174

Frequently asked questions

npx skillmds@latest add bdambrosio/check-email