Validate your first messaging API request

The customer API is JSON over HTTPS. Use your actual Convert application origin with /api/v1; for the Ruut-hosted application this is https://convert.ruut.chat/api/v1. If your organisation uses another deployment, replace the origin in every example.

Before you start

Create an API key under Account → API keys with messages:write. Copy the key when it is displayed and store it on your server. Connect and confirm the sending channel; test mode still validates required sender/channel options.

Choose a controlled recipient. Examples below use fictional addresses. Keep all API credentials out of browser JavaScript and public repositories.

Validate without delivery

Set test: true for the single-message API. This validates the recipient, channel, template, and required options without sending, creating a recipient status record, or charging the wallet. It is not a substitute for a controlled live deliverability test.

1234567891011export CONVERT_BASE_URL="https://convert.ruut.chat"
export CONVERT_API_KEY="YOUR_API_KEY"
IDEMPOTENCY_KEY="$(uuidgen)"

curl --fail-with-body "$CONVERT_BASE_URL/api/v1/messages"   -H "Authorization: Bearer $CONVERT_API_KEY"   -H "Idempotency-Key: $IDEMPOTENCY_KEY"   -H "Content-Type: application/json"   -d '{
    "to": "[email protected]",
    "channel": "email",
    "subject": "Order update",
    "message": "Hi Ada, your order has shipped.",
    "test": true
  }'

Expected success: HTTP 201, success: true, channel: "email", status: "validated", and cost: 0. The provider message ID can be absent because no message was submitted.

Move to a live request

Remove test or set it to false only when you intend delivery. Generate a new idempotency key because changing the payload creates a new request. Use the intended recipient and an active confirmed sender; review the wallet or plan allowance first.

Inspect the returned status and provider ID, then use delivery webhooks to track the outcome. A successful submission response does not guarantee arrival in an inbox.

Choose the right endpoint

One transactional notification: POST /api/v1/messages.
Many personalized notifications: POST /api/v1/messages/batch, then inspect the batch ID.
Audience campaign: use the dashboard review and launch flow.
Customer activity: use identify/events and an automation trigger.

Next: read authentication, messages, and idempotency.

Use the same key only for an identical retry. A changed recipient, OTP, template variable, channel, or test flag needs a new key.