SMS API

Send SMS messages and read inbound deliveries over a simple key-authed HTTP API, with optional real-time inbound webhooks routed by shortcode.

SMS API#

The Hep.gg SMS API lets you send outbound text messages and read the inbound messages your account has received, over a small HTTP API authenticated with a single API key. Inbound messages are routed to your account by a shortcode (the first word of the text), and you can optionally have each inbound message pushed to your own server in real time via a webhook.

Authentication#

Every call to https://sms.hep.gg/api/messages is authenticated with your API key in the Authorization header. The key is sent verbatim, with no Bearer prefix, the header value is the raw key string itself.

Authorization: <your-api-key>

Keys are created and managed in the dashboard under SMS, API Keys at hep.gg. There is no public endpoint to create a key. Your account also needs SMS sending enabled; a disabled key or a not-enabled account returns 403 (see Errors). Never commit a key to source control or print it in logs.

Quickstart#

Send your first message. Replace $SMS_KEY with the key from your dashboard and recipient with a phone number in E.164 format.

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",
  }),
});
const data = await res.json();
console.log(data);

A successful send returns 200 with a JSON payload describing the message. See Sending messages for the full request and response shape.

What you can do#

Credits#

Outbound messages cost credits. The cost is the number of 160-character segments in your content: ceil(content_length / 160), with a minimum of 1 credit per message. Credits are debited from your sms_credits balance before the message is dispatched, and the spend is written to your unified transaction log on the dashboard. Inbound messages cost 0 credits. Top up credits from the dashboard.

Endpoints at a glance#

The health check at GET https://sms.hep.gg/ is unauthenticated and returns { "data": "SMS API Online", "server": "Team Hydra" }.