Email Check

Email Check Skill

CRITICAL: Preserve Read/Unread Status

Users often use UNREAD status to track items. NEVER mark emails as read.

• Use BODY.PEEK[] NOT RFC822 (RFC822 marks as read)
• If accidentally marked read: mail.store(num, '-FLAGS', '\\Seen')

How to check emails

Use Python with imaplib. Always use BODY.PEEK[] for fetching.

import imaplib
import email
from email.header import decode_header

def check_inbox(server, email_addr, password, folder="INBOX", unseen_only=True, limit=10):
    mail = imaplib.IMAP4_SSL(server)
    mail.login(email_addr, password)
    mail.select(folder, readonly=True)  # readonly=True as extra safety

    criteria = "UNSEEN" if unseen_only else "ALL"
    status, messages = mail.search(None, criteria)
    msg_ids = messages[0].split()[-limit:] if messages[0] else []

    results = []
    for mid in msg_ids:
        # CRITICAL: BODY.PEEK not RFC822
        status, data = mail.fetch(mid, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)])")
        header = email.message_from_bytes(data[0][1])
        subject = decode_header(header.get("Subject", ""))[0][0]
        if isinstance(subject, bytes):
            subject = subject.decode(errors="replace")
        results.append({
            "from": header.get("From", ""),
            "subject": subject,
            "date": header.get("Date", "")
        })

    mail.logout()
    return results

Common tasks

Check for unread messages

Loop through configured accounts, report unread count and latest subjects per account.

Search for email from specific sender

mail.search(None, 'FROM "sender@example.com"')

Search by subject

mail.search(None, 'SUBJECT "keyword"')

Check specific folder

Gmail labels map to IMAP folders: [Gmail]/Sent Mail, [Gmail]/Drafts, [Gmail]/Spam

Date range search

mail.search(None, 'SINCE "01-Mar-2026" BEFORE "08-Mar-2026"')

Setup

Configure your accounts in environment variables or a config file:

IMAP_SERVER=imap.gmail.com
IMAP_EMAIL=you@example.com
IMAP_PASSWORD=your-app-password

For Gmail, use App Passwords (not your main password): Google Account > Security > 2-Step Verification > App passwords.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: floomhq
• Source: floomhq/moto
• License: MIT
• Homepage: https://github.com/floomhq/moto#readme

Install and usage instructions live in the source repository linked above.