Move Emails Between Folders from CLI

Command references used in this guide: nylas email list, nylas email read, nylas email search, and nylas auth login.

Why manage email folders from the CLI?

Managing email folders from the CLI means creating organizational structures, listing folder contents, and moving messages without switching to a browser or GUI client. A 2024 McKinsey report found knowledge workers spend 28% of their day managing email -- much of that time sorting messages into the right folders. CLI-based folder management fits into automation scripts that sort incoming messages by sender, project, or priority level.

Traditional IMAP clients like NeoMutt support folder operations, but each requires provider-specific configuration and can't handle Gmail's label system natively. Gmail doesn't have folders at all. It uses labels, and a single message can carry multiple labels simultaneously. The CLI abstracts this difference, presenting Gmail labels and Outlook folders through the same nylas email folders command group across all 6 supported providers.

How do you list folders and their contents?

The nylas email folders list command returns every folder (or label on Gmail) in your mailbox with its ID, name, and message count. The output includes system folders like INBOX, SENT, DRAFTS, and TRASH, plus any custom folders you've created. Gmail exposes around 12 system labels (INBOX, SENT, DRAFTS, SPAM, TRASH, etc.) plus any category tabs you've enabled. On Outlook, expect 8-12 default folders.

Once you have a folder ID, use nylas email list --folder FOLDER_ID to see messages in that specific folder. The --json flag gives you structured output for scripting. The show subcommand returns detailed information about a single folder, including its total and unread message counts.

# List all folders/labels in your mailbox
nylas email folders list

# List folders as JSON for scripting
nylas email folders list --json | \
  jq '.[] | {id: .id, name: .name, total: .total_count}'

# Show details of a specific folder
nylas email folders show FOLDER_ID

# List messages in a specific folder
nylas email list --folder FOLDER_ID --limit 20

# List messages in the Sent folder
nylas email list --folder SENT --json --limit 10

The folder ID format varies by provider. Gmail uses label IDs like Label_12345 for custom labels and names like INBOX and SENT for system folders. Outlook uses opaque IDs. The CLI accepts both the display name (for system folders) and the provider-specific ID, so --folder SENT works everywhere.

How do you create and rename folders?

Creating a folder takes a single command with the folder name as the argument. The CLI creates the folder on the provider's server immediately. On Gmail, this creates a new label. On Outlook and Exchange, it creates a traditional folder. Nested folder support depends on the provider.

Renaming works the same way: pass the folder ID and the new name. This is useful for end-of-quarter reorganization when you rename “Q1-2026” folders to “Archive/Q1-2026” or consolidate project folders after a product launch. Gmail label colors can be set through the Nylas API but aren't available as CLI flags.

# Create a new folder
nylas email folders create "Receipts"

# Create a folder (nested folder support depends on the provider)
nylas email folders create "2026"

# Rename a folder
nylas email folders rename FOLDER_ID "Receipts-Archive"

# Delete an empty folder (with confirmation)
nylas email folders delete FOLDER_ID

# Delete without confirmation prompt
nylas email folders delete FOLDER_ID --yes

Deleting a folder on Gmail removes the label but keeps the messages (they stay in All Mail). On Outlook, deleting a folder moves its contents to Deleted Items. On IMAP servers, behavior depends on the server implementation. Some move contents to Trash, others delete messages permanently. Always check folder contents with nylas email list --folder FOLDER_ID before deleting.

How do you move messages between folders?

Moving messages between folders combines the list and folder commands. The workflow is: list messages with filters, extract their IDs, then use the Nylas API to update each message's folder assignment. The CLI's nylas email list --folder FOLDER_ID --json command returns messages in a specific folder with their IDs, which you can pipe into scripts that reassign folders.

The example below shows how to identify messages in one folder and prepare them for a move operation. For simple inbox organization, you can also use nylas email list --from to find all messages from a sender, then move them to a project-specific folder. This pattern handles batch sorting of hundreds of messages in a single script run.

# List messages in INBOX from a specific sender (get IDs)
nylas email list --from invoices@stripe.com --json --limit 50 | \
  jq -r '.[].id'

# List messages in a folder as JSON
nylas email list --folder FOLDER_ID --json --limit 20

# Find all unread messages and their folder assignments
nylas email list --unread --json --limit 30 | \
  jq '.[] | {id: .id, subject: .subject, folders: .folders}'

# Count messages per folder (inbox audit)
nylas email folders list --json | \
  jq '.[] | select(.total_count > 0) | {name: .name, count: .total_count}' | \
  jq -s 'sort_by(.count) | reverse'

The CLI's folder commands handle listing and organization. To move a message to a different folder, update its folder assignment through the Nylas API -- pass the target folder ID in a PUT request to /messages/{id}. The CLI surfaces the folder IDs you need for that API call.

# Move a message to a different folder using the Nylas API
curl -X PUT "https://api.us.nylas.com/v3/grants/GRANT_ID/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folders": ["TARGET_FOLDER_ID"]}'

Get your grant ID from nylas auth show --json and the target folder ID from the nylas email folders list output above.

The folder audit command at the end shows which folders have the most messages, sorted by count. This is useful for identifying bloated folders that need cleanup. A typical Gmail account has 80% of messages in All Mail, with INBOX, SENT, and SPAM holding the rest.

How do folders map across providers (Gmail labels vs Outlook folders)?

Gmail and Outlook take fundamentally different approaches to email organization. According to Google's documentation, Gmail uses labels: a message can have 0, 1, or many labels simultaneously, and removing all labels doesn't delete the message (it stays in All Mail). Outlook uses traditional folders: a message lives in exactly 1 folder at a time, and moving it to a new folder removes it from the old one. The CLI normalizes both into the same “folders” interface, but understanding the underlying model matters for scripting.

The biggest practical difference: on Gmail, “moving” a message to a custom folder adds the label and removes the INBOX label. The message still exists in All Mail. On Outlook, a move is a true move: the message leaves one folder and enters another. When writing cross-provider scripts, always use the CLI's folder operations rather than assuming IMAP semantics, because the CLI handles the label-vs-folder translation per provider.

Next steps

• Delete and archive email — remove messages and clean up your inbox from the command line
• Read email from terminal — list, search, and read messages across providers
• Gmail CLI: list emails — Gmail-specific listing with label filtering and search operators
• Full command reference — every flag and subcommand documented