DEVELOPER API · v1

API Documentation

Mail delivery, subscriber management, A/B testing and AI proxy. REST + JSON. You can generate an API key from the editor - HMAC is optional, scope and rate limits are applied automatically based on your tier.

Generate key in editor->Pricing

1. QUICK START

Your First Request (30 seconds)

API Base URL: https://api.chairmansmsg.com/v1

When you generate a key from Editor > My Account > Developer API, the real base URL is displayed. The URL in the examples below is a placeholder; use the base URL that comes with your key.

Once you have the API key, make a call with the Authorization: Bearer bms_live_... header. /api_ping will return your scope list.

curl -X POST "https://api.chairmansmsg.com/v1/api_ping" \
  -H "Authorization: Bearer bms_live_..." \
  -H "Content-Type: application/json"

# Yanit:
# { "ok": true, "tier": "premium", "scopes": ["mail:send","subscribers:read","subscribers:write"] }

2. TIER LIMITS

API Policy by Tier

Server-side enforced - if a request is made to a scope your tier doesn't provide, it's silently rejected (403). If you exceed the rate limit, you receive 429 + retry_after_s.

Tier	API	Rate/sec	Daily	Key limit	Scopes
Free	Closed	-	-	-	-
Starter	Open	5/sn	1.000	1	mail:send
Pro	Open	30/sn	50.000	5	mail:send, subscribers:, lists:, ab:run
Enterprise	Open	200/sn	Unlimited	Unlimited	*

3. ENDPOINTS

Available Endpoints

POST/api_pingscope: herhangi

api.ep.pin.title

api.ep.pin.desc

curl example

curl -X POST "https://api.chairmansmsg.com/v1/api_ping" \
  -H "Authorization: Bearer bms_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

# Ornek yanit:
# { "ok": true, "scopes": ["mail:send","subscribers:read"], "tier": "premium" }

POST/subscribers_apiscope: subscribers:read | subscribers:write

Subscribers API

List/subscriber CRUD. Action is selected via action: list_lists | create_list | add_subscribers | remove | update.

curl example

curl -X POST "https://api.chairmansmsg.com/v1/subscribers_api" \
  -H "Authorization: Bearer bms_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

# Ornek yanit:
# { "ok": true, "lists": [...] }

POST/api_ab_campaignscope: ab:run

A/B Test Campaign

Active A/B test statistics + declaring winner. Wilson score confidence interval.

curl example

curl -X POST "https://api.chairmansmsg.com/v1/api_ab_campaign" \
  -H "Authorization: Bearer bms_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

# Ornek yanit:
# { "ok": true, "campaign_ref": "...", "winner": "B", "lift_pct": 8.4 }

POST/api_ai_proxyscope: ai:proxy

AI Proxy (Claude)

Proxy to Anthropic Claude. Token consumption is deducted from tenant credit (ai-token bucket).

curl example

curl -X POST "https://api.chairmansmsg.com/v1/api_ai_proxy" \
  -H "Authorization: Bearer bms_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

# Ornek yanit:
# { "ok": true, "completion": "...", "tokens_in": 12, "tokens_out": 96 }

4. EXTRA SECURITY

HMAC Signature (Optional)

Extra protection against key leaks during use. You sign the request body with the whsk_... secret generated alongside your key; even if your raw key leaks, unsigned requests are rejected. The server applies a +/-300 second timestamp tolerance, signature comparison is constant-time.

# 1) Timestamp + body'yi HMAC ile imzala
TS=$(date +%s)
BODY='{"hello":"world"}'
SECRET="whsk_..."
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

# 2) Istegi gonder
curl -X POST "https://api.chairmansmsg.com/v1/api_ping" \
  -H "Authorization: Bearer bms_live_..." \
  -H "X-Bms-Signature: $TS.$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

5. ERROR CODES

HTTP Responses

Code	Meaning	Action
`200`	Success	Process response body.
`401`	Unauthorized	Key missing / invalid / revoked. Generate a new key.
`403`	Forbidden (scope)	Missing scope for this endpoint or tier restricts it. Upgrade to Pro.
`429`	Rate Limit	Wait for `retry_after_s` and try again.
`5xx`	Server Error	Retry 3 times with exponential backoff; if it fails, contact support.

Need help?

Contact our support team for bugs, scope questions, or new endpoint requests.

support@chairmansmsg.com For Enterprise (enterprise@chairmansmsg.com)