Listing inbound messages

Read the last 100 inbound SMS your account has received with GET /api/messages.

Listing inbound messages#

Read the most recent inbound messages your account has received. This is the pull alternative to the inbound webhook, use it to poll for messages or to backfill what your webhook may have missed.

Request#

No body and no query parameters. The account is resolved from your API key, sent as the raw key in the Authorization header (no Bearer prefix).

curl https://sms.hep.gg/api/messages \
  -H "Authorization: $SMS_KEY"

const res = await fetch("https://sms.hep.gg/api/messages", {
  headers: { Authorization: process.env.SMS_KEY },
});
 
if (res.status === 404) {
  console.log("No inbound messages yet.");
} else {
  const messages = await res.json();
  for (const m of messages) {
    console.log(`${m.sender}: ${m.content}`);
  }
}

Response#

On success you get 200 with a JSON array of up to 100 inbound message records, ordered newest first (by created_at descending). There is no pagination; the cap is a fixed 100 rows.

[
  {
    "id": "a1b2c3d4-...",
    "userID": "your-hepgg-user-id",
    "sender": "+447700900000",
    "shortcode": "order",
    "content": "large pepperoni",
    "webhook_status": 200,
    "created_at": "2026-05-29T10:15:00.000Z"
  }
]

Empty result#

When your account has no inbound messages, this endpoint returns 404 with a response string rather than an empty array:

{
  "response": "No received messages with your short code or previous short codes."
}

Treat 404 as "no messages yet", not as an error.

Errors#

Authentication failures return the same 401 / 403 responses as the rest of the API; see Errors and status codes on the sending page.