---
title: "Forward a message"
method: POST
path: "/v1/mailboxes/{id}/messages/{messageId}/forward"
tags: ["Mailboxes"]
---

# Forward a message

`POST /v1/mailboxes/{id}/messages/{messageId}/forward`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/mailboxes/{id}/messages/{messageId}/forward`
- Auth: API key in header `x-api-key`

Forwards an email to new recipients as a new conversation from the thread's endpoint, with the original quoted below the caller's text and its attachments attached ahead of any the caller adds. The combined attachments must fit the email attachment limits.

## Path parameters

- `id` string, required
- `messageId` string, required

## Headers

- `idempotency-key` string, nullable: Optional key that makes a mailbox send idempotent for the calling key or member. Repeating the request with the same key and body returns the original action in its current state. Keep the key after a lost response. Reusing it with different content returns 409. Active actions retain their key; terminal receipts remain replayable for 24 hours.

## Request body

- ForwardMailboxMessagePayload
  - `to` string[], required
  - `cc` string[], nullable
  - `bcc` string[], nullable
  - `text` string, nullable
  - `html` string, nullable
  - `attachments` EmailAttachment[], nullable
    - `filename` string, required
    - `content` string, nullable
    - `mediaId` string
    - `contentType` string, required
    - `size` integer, required

## Response `200`

MailboxSendReceipt

- MailboxSendReceipt
  - `actionId` string, required
  - `draftId` string, required
  - `messageId` string, required
  - `threadId` string, required
  - `state` 'approvalRequired' | 'queued' | 'accepted' | 'completed' | 'notSent' | 'uncertain', required
  - `acceptedAt` string, nullable, required
  - `waitReason` 'rate' | 'daily-quota' | 'domain-health' | 'sending-paused' | 'upstream-unavailable' | 'retry' | 'campaign-paused' | 'domain-warming' | 'onboarding-review' | 'content-review' | 'screening-unavailable', nullable, required
  - `reviewExpectedAt` string, nullable, required
  - `skippedRecipients` SkippedRecipient[], required
    - `address` string, required
    - `reason` 'bounce' | 'complaint' | 'unsubscribe' | 'manual' | 'group-unsubscribe', required
    - `unsubscribeGroupId` string
  - `executeUntil` string, nullable, required
  - `retryAt` string, nullable, required
  - `problem` MailboxSendOutcome, required
    - `code` string, required
    - `message` string, required
    - `error` union
      - object
        - `_tag` 'SenderNotReadyError', required
        - `message` string, required
        - `sender` string, required
        - `retryAfterSeconds` number, nullable
      - object
        - `_tag` 'RateLimitedError', required
        - `message` string, required
        - `retryAfterSeconds` number, required
      - object
        - `_tag` 'OnboardingReviewRequiredError', required
        - `message` string, required
        - `code` 'review_required' | 'review_in_progress' | 'information_required' | 'review_rejected' | 'identity_review_required' | 'identity_review_rejected' | 'identity_changed', required
        - `decision` 'undecided' | 'approved' | 'rejected', required
        - `stage` 'collecting' | 'automated_review' | 'manual_review' | 'information_requested' | 'complete', required
        - `nextAction` 'wait_for_review' | 'provide_information' | 'verify_sending_identity' | 'reapply' | 'contact_support', required
        - `identityId` string, nullable
      - object
        - `_tag` 'PaymentRequiredError', required
        - `message` string, required
        - `resource` string, required
        - `currentUsage` number, required
        - `limit` number, required
      - object
        - `_tag` 'ValidationError', required
        - `message` string, required
        - `fields` object, nullable
      - object
        - `_tag` 'ForbiddenError', required
        - `message` string, required
      - object
        - `_tag` 'ResourceNotFoundError', required
        - `resource` string, required
        - `id` string, required
        - `message` string, required
  - `retryEligible` boolean, required
  - `decision` MailboxActionDecision, required
    - `outcome` 'allow' | 'requireApproval' | 'deny', required
    - `reason` string, nullable, required
    - `policyId` string, required
    - `source` 'grant' | 'installation' | 'policy', nullable, required
    - `decidedAt` string, required
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `202`: MailboxPendingSendReceipt
- `401`: UnauthorizedError
- `402`: PaymentRequiredError
- `403`: FlagDisabledError | MailboxSendRefusedError | OnboardingReviewRequiredError | ForbiddenError
- `404`: ResourceNotFoundError
- `409`: MailboxSendConflictError | ConflictError
- `422`: ValidationError
- `429`: RateLimitedError
- `500`: InternalError
- `502`: BillingProviderError
- `503`: SenderNotReadyError
- `504`: GatewayTimeoutError

---

[API](https://skmtc.dev/samva/apis/samva-api.md) · [All operations](https://skmtc.dev/samva/apis/samva-api/llms.txt) · [OpenAPI document](https://skmtc.dev/samva/apis/samva-api/revisions/a99408542cc3?raw)