update_mailbox
Rename an existing mailbox or move it to a new parent folder. Combine both actions in one call. IMAP credentials needed for moves.
Instructions
Rename and/or re-parent (move) an existing mailbox.
Two delivery paths:
Rename only (
new_nameset,new_parentisNone): AppleScript. Fast, no IMAP credentials needed.Move (
new_parentset; optionally combined with rename): IMAP RENAME. Requires IMAP credentials in Keychain (#73 opt-in flow) — returnserror_type: "imap_required"when missing.
At least one of new_name / new_parent must be provided.
Refused (#164): operations targeting the bare [Gmail] parent or
any [Gmail]/... child path return error_type: "unsupported_gmail_system_label". Applies to both the source
name and the resulting destination (new_parent join). Gmail's
IMAP server doesn't support normal RENAME semantics for these paths;
user-created Gmail labels (Newsletters, etc.) behave normally.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Current mailbox name. Slash-separated for nested mailboxes (e.g. ``"Archive/2024"``). | |
| account | Yes | Mail.app account display name or UUID. | |
| new_name | No | Replacement leaf name. ``None`` to keep the current leaf when moving. Path-traversal characters stripped via ``sanitize_mailbox_name``; an entirely-stripped value returns ``validation_error``. | |
| new_parent | No | Destination parent path. ``None`` keeps current parent (rename-only). ``""`` (empty string) moves to top-level. Non-empty string moves under that path. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||