---
title: "Send a message"
method: POST
path: "/v1/messages"
tags: ["Messages"]
---

# Send a message

`POST /v1/messages`

## Request

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

Sends a message on the requested channel and returns its receipt (id, status, and why it waits when it does) with a 201 Created status. Requires `messages:create` or the send permission of the channel it sends on, such as `email:send`. `channel` selects the payload variant. Repeating an identical request with the same optional `Idempotency-Key` header returns the original receipt; reusing the key for different content returns a conflict.

## Headers

- `idempotency-key` string, nullable: Optional org-scoped key that makes a send idempotent. Repeating a request with the same key and identical payload replays the original 201 response; reusing the key with different content returns 409.

## Request body

- SendMessagePayload
  - `conversationId` string
  - `metadata` MessageMetadata, nullable
  - `channel` 'email', required
  - `to` EmailRecipient[], required
    - union
      - object
        - `contactId` string, required
      - object
        - `email` string, required
        - `name` string, nullable
        - `displayName` string, nullable
  - `cc` EmailRecipient[], nullable
    - union
      - object
        - `contactId` string, required
      - object
        - `email` string, required
        - `name` string, nullable
        - `displayName` string, nullable
  - `bcc` EmailRecipient[], nullable
    - union
      - object
        - `contactId` string, required
      - object
        - `email` string, required
        - `name` string, nullable
        - `displayName` string, nullable
  - `from` EmailSender, nullable
    - `email` string, required
    - `name` string, nullable
  - `email` EmailContent, required
    - `subject` string, nullable
    - `html` string, nullable
    - `text` string, nullable
    - `attachments` EmailAttachment[], nullable
      - `filename` string, required
      - `content` string, nullable
      - `mediaId` string
      - `contentType` string, required
      - `size` integer, required
    - `publicationId` string
    - `inputContractId` string
    - `templateId` string
    - `templateSlug` string, nullable
    - `templateData` TemplateData
    - `locale` string
    - `timeZone` string
    - `inReplyToMessageId` string
    - `replyTo` string[], nullable
    - `unsubscribeGroupId` string
    - `tracking` EmailTrackingOverrideV1: Requested per-send engagement tracking policy. Recipient opt-out takes precedence, then explicit fields, organization defaults, and product defaults.
      - `opens` boolean: Override open tracking for this send. Omit to inherit the organization default. A recipient tracking opt-out always disables tracking.
      - `clicks` boolean: Override click tracking for this send. Omit to inherit the organization default. A recipient tracking opt-out always disables tracking.
    - `footer` EmailFooterOverride
      - `enabled` boolean, nullable

## Response `201`

MessageReceipt

- MessageReceipt
  - `id` string, required
  - `status` 'pending' | 'scheduled' | 'queued' | 'processing' | 'sent' | 'delivered' | 'read' | 'failed' | 'bounced' | 'complained', 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
  - `createdAt` string, required

## Other responses

- `401`: UnauthorizedError
- `402`: PaymentRequiredError
- `403`: ForbiddenError | OnboardingReviewRequiredError | FlagDisabledError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `429`: RateLimitedError
- `500`: InternalError
- `502`: BillingProviderError | ExternalServiceError
- `503`: SenderNotReadyError | DeliveryUnavailableError
- `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)