imap_copy_message

Overview

Copies a message to a destination mailbox. Supports both same-account copy (using native IMAP COPY) and cross-account copy (using FETCH + APPEND). The original message remains in the source mailbox unchanged.

This tool requires MAIL_IMAP_WRITE_ENABLED=true to be set in your environment variables. Write operations are disabled by default as a safety measure.

Common use cases

Archive messages to a different folder
Copy messages between accounts
Backup important messages
Duplicate messages to multiple mailboxes
Migrate messages across IMAP servers

Input parameters

body.account_id

string

default:"default"

Source account identifier. Must match pattern ^[A-Za-z0-9_-]{1,64}$.

body.message_id

string

required

Message identifier in format imap:{account_id}:{mailbox}:{uidvalidity}:{uid}.The account_id in the message_id must match the account_id parameter.

body.destination_mailbox

string

required

Destination mailbox name (1-256 characters). Must not contain control characters.Common mailbox names:

INBOX - Main inbox
Sent or Sent Items - Sent messages
Archive - Archived messages
Trash or Deleted Items - Deleted messages

The exact mailbox name depends on your IMAP server configuration. Use imap_list_mailboxes to see available mailboxes.

body.destination_account_id

string

Destination account identifier. Defaults to the source account_id (same-account copy).When copying to a different account:

The message is fetched from the source account
The raw RFC822 message is appended to the destination account
Both accounts must be configured in environment variables

Response

summary

string

Human-readable one-line outcome: "Message copied"

data

object

Show properties

status

string

Operation status: ok, partial, or failed

issues

array

Array of diagnostic issues encountered during execution. Each issue includes:

code - Error category (invalid_input, auth_failed, not_found, timeout, conflict, internal)
stage - Operation stage where issue occurred (e.g., connect_authenticated_source, uid_copy, fetch_raw_message_source, append_destination)
message - Actionable error message
retryable - Whether the operation can be retried
uid - Message UID (if applicable)
message_id - Message identifier (if applicable)

source_account_id

string

Source account identifier

destination_account_id

string

Destination account identifier

source_mailbox

string

Source mailbox name

destination_mailbox

string

Destination mailbox name

message_id

string

Original message identifier

new_message_id

string

New message identifier in the destination mailbox. Will be null if the server doesn’t return UID mapping (common with APPEND operations).

steps_attempted

number

Number of operation steps attempted. Useful for debugging partial failures.

steps_succeeded

number

Number of operation steps that completed successfully. Compare with steps_attempted to identify where failures occurred.

Example request

{
  "account_id": "default",
  "message_id": "imap:default:INBOX:1234567890:42",
  "destination_mailbox": "Archive"
}

Example response

{
  "summary": "Message copied",
  "data": {
    "status": "ok",
    "issues": [],
    "source_account_id": "default",
    "destination_account_id": "default",
    "source_mailbox": "INBOX",
    "destination_mailbox": "Archive",
    "message_id": "imap:default:INBOX:1234567890:42",
    "new_message_id": null,
    "steps_attempted": 2,
    "steps_succeeded": 2
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 456
  }
}

Error responses

{
  "error": {
    "code": "invalid_input",
    "message": "write tools are disabled; set MAIL_IMAP_WRITE_ENABLED=true",
    "details": {}
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 5
  }
}

Implementation notes

Same-account copy

For copies within the same account, the server uses the native IMAP UID COPY command:

Connect to the source account and authenticate (steps_attempted=1)
Select the source mailbox in read-write mode and verify uidvalidity
Execute UID COPY command (steps_attempted=2)

Cross-account copy

For copies between different accounts, the server uses FETCH + APPEND:

Connect to source account and authenticate (steps_attempted=1)
Select source mailbox (read-only) and verify uidvalidity
Fetch the raw RFC822 message from source (steps_attempted=2)
Connect to destination account and authenticate (steps_attempted=3)
Append the message to destination mailbox (steps_attempted=4)

Step tracking

The steps_attempted and steps_succeeded fields help diagnose where failures occur:

Same-account: 2 steps total (connect + copy)
Cross-account: 4 steps total (connect source + fetch + connect destination + append)

If steps_succeeded < steps_attempted, check the issues array to identify which stage failed.

Message ID availability

Same-account copies may not return new_message_id if the IMAP server doesn’t support the UIDPLUS extension
Cross-account copies using APPEND typically don’t return new_message_id
To find the copied message, search the destination mailbox using message headers or content

Overview

Account & Mailbox Tools

Read Operations

Write Operations

Overview

Common use cases

Input parameters

Response

Example request

Example response

Error responses

Implementation notes

Same-account copy

Cross-account copy

Step tracking

Message ID availability

See also

Build docs developers (and LLMs) love

Overview

Account & Mailbox Tools

Read Operations

Write Operations

​Overview

​Common use cases

​Input parameters

​Response

​Example request

​Example response

​Error responses

​Implementation notes

​Same-account copy

​Cross-account copy

​Step tracking

​Message ID availability

​See also

Build docs developers (and LLMs) love

Overview

Common use cases

Input parameters

Response

Example request

Example response

Error responses

Implementation notes

Same-account copy

Cross-account copy

Step tracking

Message ID availability

See also