Sending messages

Send an outbound SMS with POST /api/messages, including the credit cost model, response shape, and error codes.

Sending messages#

Send an outbound SMS to a single recipient. The message is dispatched through the phone gateway and the cost is debited from your sms_credits balance.

Request#

Send the body as application/x-www-form-urlencoded (JSON is also accepted). Authenticate with your raw API key in the Authorization header, with no Bearer prefix.

The sender is fixed server-side (defaults to +2899682626); callers cannot set it.

Credit cost#

Each message costs one credit per 160-character segment:

creditCost = max(1, ceil(content_length / 160))

So a 1 to 160 character message costs 1 credit, 161 to 320 costs 2, and so on. Credits are debited atomically from your sms_credits balance before the message is dispatched. If your balance is lower than the cost, the send is rejected and nothing is debited. Each spend is recorded in your unified transaction log on the dashboard.

Response#

On success you get 200 with the sent-message payload.

{
  "ID": "a1b2c3d4-...",
  "sent_from": "+2899682626",
  "sent_to": "+447700900000",
  "sent_to_parsed": {
    "isValid": true,
    "phoneNumber": "+447700900000",
    "countryIso2": "GB",
    "countryIso3": "GBR",
    "countryCode": "+44"
  },
  "content": "Hello from Hep.gg",
  "owner": "your-hepgg-user-id",
  "creditCost": 1
}

Examples#

curl -X POST https://sms.hep.gg/api/messages \
  -H "Authorization: $SMS_KEY" \
  -d "recipient=+447700900000" \
  -d "content=Hello from Hep.gg"

const res = await fetch("https://sms.hep.gg/api/messages", {
  method: "POST",
  headers: {
    Authorization: process.env.SMS_KEY,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    recipient: "+447700900000",
    content: "Hello from Hep.gg",
  }),
});
 
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`SMS send failed: ${error}`);
}
 
const message = await res.json();
console.log(message.ID, message.creditCost);

Errors and status codes#

Validation and entitlement failures return 400 with a JSON error string. Authentication failures from the auth layer return 401 or 403.

There is no rate-limit response documented and no pagination; this endpoint sends exactly one message per call.