What those CLI commands are for:
- reading emails from your connected accounts
- sorting/processing them
What they’re not for:
- sending bulk email campaigns (we love Resend for that)
Should you need help with the CLI syntax, you can always invoke:
In IMAP, emails are bound to a folder. So if you move an email to another folder, it will create a new UID.
Consider the MIME email head Message-ID if you want a global unique identifier for an email
List your recent emails
Display your recent emails in a formatted table with UID, timestamp, sender, subject, and snippet.
Alias: relay messages ls
Shows the 20 most recent emails from your first configured account.
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
--limit | -l | Number of messages to fetch | 20 |
--unread | -u | Show only unread messages | false |
The table displays: UID, Timestamp (UTC), From, Subject, and Snippet for easy scanning.
Search your inbox
Search for messages containing specific text in the subject, sender, or body.
relay messages search "meeting"
relay messages find, relay messages grep
Searches through the most recent 100 messages for the term “meeting”.
Search behavior
The search function:
- Searches in subject lines, sender addresses, and message body text
- Is case-insensitive
- Returns results sorted by date (newest first)
- Shows the same table format as the list command
Use specific search terms to narrow down results. The search looks through subject, sender, and body content.
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
--limit | -l | Number of messages to search | 100 |
Read a specific email
Display the full content of a specific email message by its UID.
relay messages open 12345
relay messages cat
Opens the message with UID 12345 from your first configured account.
Message display
The command shows:
- Message Details: UID, timestamp, subject
- Headers: From, CC, BCC
- Body: Plain text content
- Attachments: List with filenames, content types, and sizes
The UID is specific to each account and folder. You can get UIDs from the relay messages list command.
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
Move an email to trash
Move a specific email message to the trash folder.
relay messages trash 12345
relay messages rm
Moves the message with UID 12345 to trash.
This moves the email to your email provider’s trash folder. The behavior depends on your email provider’s trash handling.
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
Mark an email as spam
Mark a specific email message as spam.
relay messages spam 12345
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
Mark an email as read/unread status
Change the read status of a specific email message.
Mark as Read
Mark as Unread
relay messages mark read 12345
relay messages mark unread 12345
Status options
| Status | Description |
|---|
read | Mark the message as read |
unread | Mark the message as unread |
Options
| Option | Short | Description | Default |
|---|
--account | -a | Account name to use | First configured account |
The read/unread status is synchronized with your email provider, so changes will be reflected in other email clients.
