SMS Messages - Bar9 Developer Docs

Overview

The Messages API queues outbound SMS and returns 202 Accepted. The backend processes queued messages in the API process, sends them through the configured SMS provider, then updates the message status.

Credits are debited before the message is created. The cost is 5 credits per segment, with one segment per 160 characters.

Send a message

curl https://api.bar9.me/v1/messages \
  -H "Authorization: Bearer $BAR9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+213661000000",
    "body": "Your verification code is 7734",
    "client_reference": "order-1001"
  }'

Send messages in bulk

curl https://api.bar9.me/v1/messages/bulk \
  -H "Authorization: Bearer $BAR9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+213661000000",
        "body": "Campaign message #1",
        "client_reference": "bulk-campaign-1001-1"
      },
      {
        "to": "+213661000001",
        "body": "Campaign message #2",
        "client_reference": "bulk-campaign-1001-2"
      }
    ]
  }'

Bulk requests accept from 1 to 100 message objects. Validation and message fields are the same as single-message sends.

Bulk response

{
	"ok": true,
	"data": {
		"count": 2,
		"messages": [
			{
				"id": "msg_...",
				"to": "+213661000000",
				"sender": "BAR9",
				"body": "Campaign message #1",
				"type": "message",
				"status": "queued",
				"provider_message_id": null,
				"segments": 1,
				"cost_credits": 5,
				"client_reference": "bulk-campaign-1001-1",
				"created_at": 1778407200,
				"queued_at": 1778407200,
				"sent_at": null,
				"delivered_at": null,
				"failed_at": null,
				"failure_reason": null
			}
		]
	}
}

Request fields

Field	Required	Notes
`to`	Yes	E.164 phone number, for example `+213661000000`.
`body`	Yes	Required, maximum 2000 characters.
`client_reference`	No	Maximum 120 characters. Used as a client-side message reference.
`type`	No	Defaults to `message`; `otp` is used internally by the OTP API.

Response

{
	"ok": true,
	"data": {
		"id": "msg_...",
		"to": "+213661000000",
		"sender": "BAR9",
		"body": "Your verification code is 7734",
		"type": "message",
		"status": "queued",
		"provider_message_id": null,
		"segments": 1,
		"cost_credits": 5,
		"client_reference": "order-1001",
		"created_at": 1778407200,
		"queued_at": 1778407200,
		"sent_at": null,
		"delivered_at": null,
		"failed_at": null,
		"failure_reason": null
	}
}

List filters

GET /v1/messages supports standard pagination plus these filters:

Query	Notes
`page`	Page number.
`per_page`	Items per page.
`status`	Filter by message status.
`type`	Filter by `message` or `otp`.
`to`	Filter by recipient.
`client_reference`	Find messages tied to your reference.

List responses omit body to keep history payloads smaller. Fetch an individual message to retrieve the body.