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

# Send a new message

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

## Request

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

Starts a new conversation from the mailbox's default endpoint on the channel the body names (email when omitted); a mailbox with no endpoint on that channel is refused (422). A message to a number joins the mailbox's thread with that number when it has one. Records a send action and returns 202 with its current receipt and a Location for action status. An installation, grant, or policy may require approval; otherwise the send is queued. Observe the same action through acceptance and mailbox completion. A policy refusal returns 403 with the recorded receipt.

## Path parameters

- `id` 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

- SendMailboxMessagePayload
  - `channel` 'email', nullable
  - `to` string[], required
  - `cc` string[], nullable
  - `bcc` string[], nullable
  - `replyTo` string[], nullable
  - `subject` string, required
  - `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)