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

# Send a message

`POST /v1/messages/send`

## Request

- Base URL: `https://api.replylayer.ai`
- URL: `https://api.replylayer.ai/v1/messages/send`
- Auth: HTTP bearer

## Headers

- `idempotency-key` string

## Request body

- object
  - `attachment_ids` string[]
  - `body` string, required
  - `from_mailbox` string
  - `html` string
  - `subaddress_instance_id` string
  - `subaddress_mode` 'reply_to' | 'from' | 'none'
  - `subject` string
  - `thread_id` string
  - `to` string, email

## Response `200`

Success

- object
  - `agent_safety_context` object, nullable
    - `guidance` string, required
    - `instruction_trust` object
      - `match` 'address', required
      - `provenance` 'managed', required
      - `verdict` 'verified_aligned', required
      - `verified_domain` string, nullable, required
      - `version` 'v1', required
    - `untrusted_content` boolean, required
  - `daily_limit` integer, required
  - `email_effect` object
    - `effect_status` 'sent' | 'held_for_review' | 'held_infrastructure' | 'blocked', required
    - `releasable` boolean, required
    - `retryable` boolean, required
    - `terminal` boolean, required
  - `hold_context` object, nullable
    - `agent_instructions` string[]
    - `review_causes` string[], nullable
    - `review_expires_at` string, date-time
    - `review_url` string
    - `summary_reasons` string[], required
    - `trigger_source` 'mailbox_policy' | 'scanner' | 'both', required
  - `html_sanitized` boolean
  - `message_id` string, required
  - `removed_categories` string[]
  - `scan` object, nullable
    - `categories` object[], required
      - `category` string, required
      - `decision` 'allow' | 'allow_with_warning' | 'quarantine' | 'require_human_approval' | 'block', required
    - `findings` object[], required
      - `agent_instructions` string[]
      - `attachment_filename` string
      - `attachment_index` integer
      - `attachment_policy_action` 'quarantine_message' | 'metadata_only_after_rewrite' | 'derived_text_finding'
      - `category` string, required
      - `decision` 'allow' | 'allow_with_warning' | 'quarantine' | 'require_human_approval' | 'block', required
      - `expires_at` string, date-time
      - `failure_class` 'inference_error' | 'model_judgment'
      - `pii_type` 'ssn' | 'credit_card' | 'phone_number'
      - `reason` string, nullable, required
      - `retryable` boolean
      - `subtype` string
      - `warning` object
        - `affected_urls` string[], required
        - `attribution_text` string, required
        - `attribution_url` string, required
        - `learn_more` object[], required
          - `threat_type` 'MALWARE' | 'SOCIAL_ENGINEERING' | 'UNWANTED_SOFTWARE' | 'SOCIAL_ENGINEERING_EXTENDED_COVERAGE', required
          - `url` string, required
        - `qualified_wording` string, required
    - `verdict` 'clean' | 'warning' | 'review_required' | 'blocked' | 'quarantined', required
  - `sends_remaining` integer, required
  - `status` 'sent' | 'quarantined' | 'blocked' | 'pending_review', required
  - `warning` string, nullable

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key (code: UNAUTHORIZED)
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `422`: Unprocessable entity
- `429`: Rate limited
- `500`: Internal error (code: INTERNAL_ERROR)
- `503`: Temporarily unavailable

---

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