Delete and Archive Email from CLI

Command references used in this guide: nylas email list, nylas email delete, nylas email mark read, and nylas email threads delete.

Why delete email from the CLI?

Deleting email from the CLI means removing messages from your mailbox without switching to a browser, Outlook desktop client, or mobile app. Developers who process 121 emails per day (the average for business users, per a 2023 Radicati Group study) can automate cleanup of newsletters, expired notifications, and old threads directly from the terminal. CLI-based deletion fits into scripts, cron jobs, and AI agent workflows where manual cleanup doesn't scale.

Traditional tools like NeoMutt and aerc support IMAP deletion, but each requires per-provider configuration and can't target messages by metadata (sender, date, read status) in a single pipeline. The CLI outputs JSON, so you can filter messages with jq, pipe IDs to the delete command, and remove 100 messages in one shell loop.

How do you delete a single email?

Deleting a single email moves the message to the provider's trash folder. On Gmail, trashed messages auto-delete after 30 days per Google's retention policy. Outlook keeps trashed items for 30 days by default, and admins can change the deleted item retention period from 1 to 30 days. The CLI's nylas email delete command takes a message ID and works identically across all 6 supported providers.

First, find the message you want to remove. Use nylas email list --json and pipe through jq to extract message IDs. Once you have the ID, the delete command is a single line.

# List recent emails and extract their IDs
nylas email list --json | jq -r '.[].id'

# Delete a specific message by ID
nylas email delete MESSAGE_ID

# Skip the confirmation prompt with --yes
nylas email delete MESSAGE_ID --yes

# Delete an entire thread (all messages in the conversation)
nylas email threads delete THREAD_ID

The --yes flag skips the confirmation prompt, which is useful inside scripts. Without it, the CLI asks for a yes/no before deleting. Thread deletion removes every message in the conversation at once, which is faster than deleting 8-12 individual replies in a long chain.

How do you bulk-delete old messages?

Bulk deletion combines nylas email list --json with standard Unix tools. The JSON output includes every message's id, date, from, and unread fields, so you can filter by any combination before passing IDs to nylas email delete. This pipeline approach lets you remove 50, 100, or 500 messages in a single script run.

The example below deletes all read emails from a specific sender. You can swap the jq filter for any condition: messages older than 90 days, newsletters from a particular domain, or unstarred promotions. The --limit flag controls batch size, and --yes skips per-message confirmation prompts.

# Delete all read messages from a specific sender
nylas email list --from newsletters@example.com --json --limit 50 | \
  jq -r '.[] | select(.unread == false) | .id' | \
  xargs -I {} nylas email delete {} --yes

# Delete messages older than 90 days (using jq date filter)
nylas email list --json --limit 200 | \
  jq -r --arg cutoff "$(date -d '-90 days' +%s 2>/dev/null || date -v-90d +%s)" \
    '.[] | select(.date < ($cutoff | tonumber)) | .id' | \
  xargs -I {} nylas email delete {} --yes

# Count how many messages match before deleting
nylas email list --from notifications@github.com --json --limit 100 | \
  jq 'length'

Always run the jq 'length' count first to verify how many messages match your filter. Bulk deletion is irreversible once messages leave the trash retention window. For Gmail, that window is 30 days; for Exchange, it depends on admin-configured retention policies.

How do you archive instead of delete?

Archiving removes a message from your inbox without deleting it. On Gmail, archiving strips the INBOX label and moves the message to All Mail. On Outlook, archiving moves messages to the Archive folder. According to Google's documentation, archived messages remain searchable and count toward your 15 GB storage quota.

The CLI doesn't have a dedicated archive command. Archiving means moving a message out of the inbox, which requires a Nylas API call to update the message's folder. The CLI can list your folder IDs to find the target.

# List folders to find the Archive folder ID
nylas email folders list --json | jq '.[] | {id, name}'

# Use the Nylas API to move a message to the archive folder
curl -X PUT "https://api.us.nylas.com/v3/grants/GRANT_ID/messages/MESSAGE_ID" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folders": ["ARCHIVE_FOLDER_ID"]}'

For a CLI-only workflow, use nylas email mark read to mark messages as read, then filter your inbox view to unread messages. This approximates archiving without an API call. The jq + xargs pattern from the bulk-delete section works here too.

# Mark messages as read in bulk (CLI-only archive alternative)
nylas email list --unread --json --limit 20 | \
  jq -r '.[].id' | \
  xargs -I {} nylas email mark read {}

How does cleanup differ across providers?

Each email provider handles deletion and archiving differently at the protocol level. Gmail uses labels instead of folders, so “deleting” a message means adding the TRASH label and removing INBOX. Outlook and Exchange use traditional folders with server-side move operations. Yahoo and iCloud follow standard IMAP conventions where deletion sets the \Deleted flag. The CLI normalizes these differences, but the underlying behavior varies.

Yahoo's 7-day trash retention is the shortest among major providers. If you're running bulk cleanup scripts against a Yahoo account, messages become permanently unrecoverable faster than on Gmail or Outlook. Always test your delete filters on a small batch first.

Next steps

• Read email from terminal — list, search, and read messages before deciding what to delete
• Move emails between folders — organize messages into folders instead of deleting them
• Send email from terminal — send messages without an SMTP server or Postfix
• Full command reference — every flag and subcommand documented