shellmail_skill

Overview

This skill provides an Email API interface for AI agents via ShellMail. It enables creating inboxes, checking messages, reading emails, extracting OTP/verification codes, and basic mailbox management from an agent workflow. The skill triggers on email-related intents like "check email", "inbox", "otp", and "verification code".

How this skill works

The skill uses ShellMail's API and a stored SHELLMAIL_TOKEN to list mail, read messages, search content, and fetch OTPs. It exposes commands for inbox checks, reading specific messages, waiting for OTPs with optional sender filters, and performing mailbox actions (mark read, archive, delete). When no token exists, the skill guides the user to create an address and save the returned token securely.

When to use it

• Automatically check an inbox for new or unread messages.
• Extract one-time passwords or verification codes from incoming mail.
• Search messages by text, sender domain, or OTP presence.
• Read full email content or preview a specific message by ID.
• Perform mailbox housekeeping: mark read, archive, or delete messages.

Best practices

• Keep SHELLMAIL_TOKEN stored securely; it won’t be retrievable after creation.
• Use the --unread flag for quick checks and limit noise when scanning inbox.
• Use --wait with otp to poll for incoming verification codes within a timeout window.
• Filter OTP requests by sender domain to reduce false positives (e.g., --from github.com).
• Archive or delete messages after processing OTPs to keep the inbox manageable.

Example use cases

• Agent told "check my email" runs an inbox --unread to surface recent messages.
• Agent completing multi-factor login waits for the provider OTP with otp --wait 30.
• Agent onboarding a new account creates an address and stores the returned token.
• Automated test harness searches for emails containing "verification" to validate signups.
• Cleanup workflow archives or deletes processed messages using archive/delete commands.