| name | check-mail |
| description | Check your agent-mail inbox for new messages, read them, and archive handled ones. Use at the start of a work session or when expecting replies. |
| allowed-tools | bash read |
Check Mail
Check your inbox, read new messages, and archive ones you've handled.
Prerequisites
Resolve your persona first:
agent-mail persona current --json
This reads .agent-mail/identities.toml in the project and returns your persona name.
Use that name wherever <you> appears below. Do not register a new durable persona unless the user explicitly asks for setup work. If you're a one-off agent with no resolved persona, mint a throwaway one instead — see the ephemeral-identity skill — and use its name (or AGENT_MAIL_PERSONA) wherever <you> appears.
Workflow
1. Check for new messages
agent-mail count --persona <you> --new-only --json
If count is 0, you're caught up — stop here.
2. List new messages
agent-mail ls --persona <you> --new-only --json
3. Read each message
agent-mail read '<message-id>' --persona <you> --json
Reading marks the message as Seen.
4. Recover thread context when needed
If the message is part of an ongoing conversation, inspect the thread before replying or acting:
agent-mail thread '<message-id>' --persona <you> --json
Use this when the current message references prior work, follow-ups, or multiple participants.
5. Act on each message
After reading, decide:
- Reply needed → use the
reply-mail skill
- Just informational → archive it
- Needs work first → do the work, then usually reply to the sender; use
report-progress as additional stakeholder communication when appropriate
6. Archive handled messages
agent-mail move '<message-id>' --persona <you> --to archive
Archive messages once you've handled them. Keep your inbox as a todo list — only unhandled items stay.
Tips
- Use
--json for machine-readable output when parsing programmatically.
- Check mail at natural breakpoints: start of session, after completing a task, before reporting progress.
- Don't poll in a tight loop. Check when you have reason to expect a reply.
- If you only need to understand a message quickly,
read is enough; if you need conversation history, use thread.
