URL: https://docs.sent.dm/llms/reference/api/messages/SentDmServicesEndpointsCustomerAPIv3MessagesSendMessageV3Endpoint.txt

# POST /v3/messages

Send a message

Sends a message to one or more recipients using a template. Supports multi-channel broadcast — when multiple channels are specified (e.g. ["sms", "whatsapp"]), a separate message is created for each (recipient, channel) pair. Returns immediately with per-recipient message IDs for async tracking via webhooks or the GET /messages/{id} endpoint. Account-level preconditions such as insufficient balance do not reject the request: the send is accepted with 202 and the affected messages are reported as BLOCKED on GET /messages/{id} and the message status webhook.

**Operation ID:** `SentDmServicesEndpointsCustomerAPIv3MessagesSendMessageV3Endpoint`

**Tags:** Messages

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Idempotency-Key` | `string` | false | Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer. |
| `x-profile-id` | `string` | false | Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization. |

## Request Body

### application/json

```typescript
{
  sandbox?: boolean,
  to?: Array<string>,
  channel?: Array<string>,
  template?: {
    id?: string,
    name?: string,
    parameters?: object
  },
  text?: string
}
```

## Responses

### 202

Message accepted for processing

#### application/json

```typescript
{
  success?: boolean,
  data?: {
    status?: string,
    template_id?: string,
    template_name?: string,
    recipients?: Array<{
      message_id?: string,
      to?: string,
      channel?: string,
      body?: string
    }>
  },
  error?: {
    code?: string,
    message?: string,
    details?: object,
    doc_url?: string
  },
  meta?: unknown
}
```

##### Example

```json
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "recipients": [
      {
        "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155551234",
        "channel": "sms",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "8ba7b831-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155551234",
        "channel": "whatsapp",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155555678",
        "channel": "sms",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "9ba7b841-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155555678",
        "channel": "whatsapp",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-07-27T14:19:54.3693106+00:00",
    "version": "v3"
  }
}
```

### 400

Invalid request parameters

#### application/json

```typescript
{
  success?: boolean,
  error?: {
    code?: string,
    message?: string,
    details?: object,
    doc_url?: string
  },
  meta?: unknown
}
```

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_004",
    "message": "Request validation failed",
    "details": {
      "to": [
        "'to' must contain at least one recipient"
      ],
      "template": [
        "'template' is required"
      ]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-07-27T14:19:54.3693138+00:00",
    "version": "v3"
  }
}
```

### 401

Unauthorized - Invalid API credentials

### 403

Forbidden

### 404

Template not found

#### application/json

```typescript
{
  success?: boolean,
  error?: {
    code?: string,
    message?: string,
    details?: object,
    doc_url?: string
  },
  meta?: unknown
}
```

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_002",
    "message": "Template not found",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-07-27T14:19:54.3693145+00:00",
    "version": "v3"
  }
}
```

### 500

Internal server error

#### application/json

```typescript
{
  success?: boolean,
  error?: {
    code?: string,
    message?: string,
    details?: object,
    doc_url?: string
  },
  meta?: unknown
}
```

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "Failed to queue message for processing.",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-07-27T14:19:54.369315+00:00",
    "version": "v3"
  }
}
```

## Security

- **CustomerApiKey**