Organize mail

Mark read or unread

icloud mail mark-read msg_…
icloud mail mark-unread msg_…

Flag or unflag:

icloud mail flag msg_…
icloud mail unflag msg_…

If the same message has eligible copies in several folders, choose the one you mean:

icloud mail mark-read msg_… --folder inbox

Move a message

Preview the move:

icloud mail move msg_… --from inbox --to Projects --dry-run

Then run it with a stable idempotency key:

icloud mail move msg_… \
  --from inbox \
  --to Projects \
  --idempotency-key move-project-01 \
  --yes

Copy a message

icloud mail copy msg_… --from inbox --to Projects --dry-run

Copy keeps the source location. Move changes it.

Archive

icloud mail archive msg_… --dry-run
icloud mail archive msg_… \
  --from inbox \
  --idempotency-key archive-01 \
  --yes

The Archive destination comes from the account’s recognized or configured Archive role. See Folders if that role cannot be resolved.

Trash and restore

icloud mail trash msg_… --dry-run

Restore a trashed message:

icloud mail restore msg_… --from trash --to inbox --dry-run

For a real location change, add the idempotency key and --yes shown by the command’s help.

Mark as junk or not junk

icloud mail junk msg_… --dry-run
icloud mail not-junk msg_… --dry-run

These use the recognized Junk and Inbox locations rather than guessing from arbitrary folder names.

Permanently delete one location

Permanent deletion is separate from moving to Trash:

icloud mail delete msg_… --from trash --dry-run

Then:

icloud mail delete msg_… \
  --from trash \
  --idempotency-key delete-01 \
  --yes

Use Empty Trash, Junk, or a folder when you want to permanently delete a reviewed page of messages rather than one exact target.

Change several explicit messages

Most state and location actions accept up to 100 explicit message IDs in one bounded request:

icloud mail move msg_… msg_… \
  --from inbox \
  --to Projects \
  --idempotency-key move-batch-01 \
  --yes \
  --jsonl

For a search-derived set that you want to freeze and review before acting, use Reviewed bulk actions.

Apply an action to a conversation

Thread commands use the same familiar actions:

icloud mail threads mark-read thr_… --folder inbox
icloud mail threads archive thr_… --from inbox --dry-run

See Conversations and threads.

If an operation becomes uncertain

Do not blindly repeat a location-changing command with a new key. Inspect the operation and current message state:

icloud mail operations mutations list
icloud mail message show msg_… --metadata-only

Then synchronize the source and destination folders. Reusing the original request with the same idempotency key retrieves the recorded operation instead of creating a new one.