# Send a dispatch message

_Dispatch / Message_

`POST /dispatch/{bucketId}`

## Parameters

- `bucketId` (string, required) — Project (bucket) identifier
- `x-api-key` (string, required) — API key passed in the request header for authentication

## Request Body

### `CreateDispatchRequest`

- `subject` (string, required) — Message subject line
- `messageType` (number, required) — Delivery channel: 1 = Email, 2 = SMS, 3 = Push, 4 = Messenger
- `recipients` (string[], required) — Array of recipient addresses (email addresses, phone numbers, or channel-specific IDs)
- `htmlBase64Body` (string, optional) — Base64-encoded HTML message body. At least one of htmlBase64Body or plainBase64Body is required
- `plainBase64Body` (string, optional) — Base64-encoded plain-text message body. At least one of htmlBase64Body or plainBase64Body is required
- `providerId` (string, optional) — ID of the specific dispatch provider to use. If omitted, the matching dispatch rule is resolved automatically for the bucket
- `delay` (number, optional) — Delivery delay in seconds
- `env` (string, optional) — Environment tag (e.g. production, staging)
- `timeStamp` (number, optional) — Unix timestamp of the event (milliseconds). Defaults to server time if omitted
- `appName` (string, optional) — Name of the sending application. Defaults to "unknown" if omitted
- `appVersion` (string, optional) — Version of the sending application
- `correlationId` (string, optional) — Caller-supplied correlation ID for distributed tracing
- `tags` (string[], optional) — Arbitrary string tags attached to the message for filtering
- `userAgent` (string, optional) — User-agent string of the originating client
- `ip` (string, optional) — IP address of the originating client
- `runtime` (number, optional) — Runtime identifier byte
- `runtimeVersion` (string, optional) — Runtime version string

## Responses

### `201` — Message accepted and enqueued for delivery.

Type: `ApiResponse<bool>`

- `success` (boolean) — Always true on success
- `result` (boolean) — true when the message was successfully enqueued
- `errors` (ErrorDetail[]) — Empty on success

### `400` — Validation failed — subject, message body, recipients, or messageType missing; or no dispatch rule found for the bucket.

Type: `ApiResponse<T>`

- `isValid` (boolean) — Always false
- `validationErrors` (ValidationError[]) — List of validation failures
  - `name` (string) — Field that failed validation
  - `attemptedValue` (object) — Value that was submitted
  - `message` (string) — Human-readable validation message

### `401` — Unauthorized — API key is missing or invalid.


### `500` — Unexpected server error.

Type: `ApiResponse<T>`

- `success` (boolean) — Always false
- `errors` (ErrorDetail[]) — Server-side errors
  - `correlationId` (string) — Trace ID
  - `message` (string) — Error message
  - `stack` (string) — Stack trace (non-production only)


## Code Examples

### curl

```curl
curl --request POST \
  --url https://apis-spb.konso.io/dispatch/{bucketId} \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"subject":"Hello","messageType":1,"recipients":["user@example.com"],"htmlBase64Body":"SGVsbG8gV29ybGQ="}'
```

### javascript

```js
fetch('https://apis-spb.konso.io/dispatch/{bucketId}', {
  method: 'POST',
  headers: {
    'x-api-key': '<your-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: 'Hello',
    messageType: 1,
    recipients: ['user@example.com'],
    htmlBase64Body: btoa('<h1>Hello World</h1>')
  })
})
  .then(res => res.json())
  .then(console.log);
```

### dotnet

```dotnet
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "<your-api-key>");

var payload = new {
    subject = "Hello",
    messageType = 1,
    recipients = new[] { "user@example.com" },
    htmlBase64Body = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("<h1>Hello World</h1>"))
};

var response = await client.PostAsJsonAsync("https://apis-spb.konso.io/dispatch/{bucketId}", payload);
```

### python

```python
import requests, base64

headers = {'x-api-key': '<your-api-key>', 'Content-Type': 'application/json'}
payload = {
    'subject': 'Hello',
    'messageType': 1,
    'recipients': ['user@example.com'],
    'htmlBase64Body': base64.b64encode(b'<h1>Hello World</h1>').decode()
}
response = requests.post('https://apis-spb.konso.io/dispatch/{bucketId}', json=payload, headers=headers)
print(response.json())
```

### Request Body Example

```json
{
  "bucketId": "example-string",
  "x-api-key": "example-string"
}
```

### Response Example (201)

```json
{
  "success": true,
  "result": true,
  "errors": []
}
```