# messages.copy

Copy or move messages and conversations into another mailbox.

Stores each message again, from its original bytes, in a folder of another mailbox you can reach, with its flags, keywords and received time. With `move`, each message that landed is then deleted from this mailbox (recoverably, as DELETE /messages does). Within ONE mailbox use PATCH /messages instead: a label is a copy there, and nothing is duplicated.

You need `r` here (and `t` to move) and `i` on the destination. A folder-scoped grant works on either side: messages outside your folders are `not_found`, and `toLabel` must be one of your folders in the destination.

The call answers ONE PAGE of up to 20 messages. While `nextAfter` is not null, repeat the request with the same operands and `after` set to it. `nextAfter` is also null once the destination has refused a message (over quota, gone): the gesture is over, and `remaining` says how much was never attempted. Send one `gestureId` for the whole gesture: a retried page then answers `duplicate` for what it already stored instead of storing it twice.

```ts
openemail.messages.copy(
  mailboxId: string,
  body: MessagesCopyBody,
  options?: CallOptions,
): ApiPromise<MessageCopyResult>
```

It calls `POST /mailboxes/{mailboxId}/messages/copy`: [Copy or move messages and conversations into another mailbox](/docs/api/messages/post_MessageCopy) in the API reference.

## Example

```ts
const messageCopyResult = await openemail.messages.copy(mailboxId, { toMailboxId: '…', toLabel: '…' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | The SOURCE mailbox ULID — the one the messages are read from. The path's `{mailboxId}`. |
| `body` | [`MessagesCopyBody`](#messagescopybody) | The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`MessageCopyResult`](/docs/sdks/typescript/types/message-copy-result). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed, target_required (neither ids nor threadIds), same_mailbox, gesture_required (a move without gestureId), thread_context_required, thread_too_large, or unknown_label — with `label` naming the folder: `toLabel` when it is no folder you can file into in the destination, `threadLabel` when it is no folder of yours here |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | not_found — either mailbox is missing or not accessible with the rights this needs |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### MessagesCopyBody

```ts
/** The body of `messages.copy`. */
type MessagesCopyBody = {
  /** The previous page's `nextAfter` */
  after?: string
  /** Your idempotency token for this gesture, the same on every page and every retry of it, and new for every new gesture. Required on a move. Omitted on a copy, every call is its own intent and a retry stores a second copy. */
  gestureId?: string
  /** Message IDs to copy */
  ids?: string[]
  /** Delete each source message once its copy has landed. Only landed messages are deleted, and a failed delete is reported per message (`sourceRemoved: false`), never by undoing the copy. REQUIRES `gestureId` (gesture_required without it): a move is two commits in two stores, and the token is what lets a retry finish one that stopped between them instead of copying it again. */
  move?: boolean
  /** Conversation IDs whose members to copy, expanded server-side on every page exactly as on PATCH /messages. Refused with thread_too_large past 1000 expanded messages. */
  threadIds?: string[]
  /** The folder each conversation in `threadIds` was being viewed in, as on PATCH /messages. REQUIRED with `threadIds` on a move, as it is on DELETE /messages, because a move deletes what it expanded. */
  threadLabel?: string
  /** Narrow each conversation to the members FILED UNDER `threadLabel`, as on PATCH /messages — so a conversation moved out of the Inbox does not take the Sent copy of your replies with it. */
  threadLabelOnly?: boolean
  /** The destination folder, by name. It must exist; it is never created. */
  toLabel: string
  /** The destination mailbox ULID */
  toMailboxId: string
}
```

It names these types of the API, each on a page of its own: [`MessageCopyResult`](/docs/sdks/typescript/types/message-copy-result).
