Messages

Send an SMS

Sends one transactional SMS: an order confirmation, a shipping update with track and trace, an appointment reminder. Not for marketing: promotional SMS needs the recipient's prior consent under marketing law, and this endpoint is not built for bulk. A message goes to a mobile number in a country your project can text; an unsupported destination returns destination_not_allowed with a reason. It comes from an alphanumeric sender (your project name, or from); your phone numbers cannot send SMS. At most 6 segments per message, 30 messages per minute and 200 per day per project. A new live project starts lower (20 per day, 60 after 7 days and a first top-up, the full limit after 30 days and €25 paid). The same number gets at most 3 messages in 24 hours per project and 10 across all projects: 429 message_limit_reached with scope per_number or per_number_platform, retry_at and a user_message; test numbers do not count. A live key needs the company verification level (company details, spending cap, payment method, a verified phone and one payment confirmed with your bank: iDEAL or a card with 3D Secure); a business may also need its registration number checked against the business register, and a personal account may need our approval of its identity documents (the number_documents level); otherwise the request returns verification_required. Live messages are deducted from your prepaid balance per segment (the rate is under Billing in the portal; test mode is free) and count toward the spending cap. If the balance is too low for this message, the request returns insufficient_balance; if this month's spending plus this message would exceed the cap, it returns billing_blocked. In both cases nothing is sent. The response says queued; message.delivered or message.failed follows as a webhook, and GET /messages/{id} shows the status. With a test key nothing is sent: use a test number from +447700900000 to +447700900999; the message is delivered immediately, and +447700900999 simulates a failure. Send an Idempotency-Key (one per order event, like order-10432-shipped) so a retry never sends the SMS twice.

post/messages

Request

  • Base URL: https://api.hypamoon.com/api/v1
  • URL: https://api.hypamoon.com/api/v1/messages
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.hypamoon.com/oauth/authorize, token URL https://api.hypamoon.com/oauth/token, scopes: messages:write)

Headers

Idempotency-Keystring

Optional but recommended: 1 to 255 visible ASCII characters without spaces. Reuse it when you retry; the same key within 24 hours returns the same message instead of sending a second one.

Request body

tostring required

The recipient in E.164. Live: a mobile number in a country your project can text (otherwise destination_not_allowed with a reason). Test mode: a test number from +447700900000 to +447700900999.

bodystring required

The text. At most 6 SMS segments: 918 characters in plain text (GSM-7), 402 with an emoji or another character outside GSM-7. Typographic quotes and dashes are replaced by plain ones.

fromstring

Optional sender name: 1 to 11 letters, digits and spaces, with at least one letter. Default: your project name. A phone number is not possible.

referencestring

Optional: your own id for this message, like an order number. Comes back in the message and its webhooks.

Response

The message was accepted (or, in test mode, simulated).

idstring uuid required

The id of the message.

tostring required

The recipient, in E.164.

fromstring required

The sender the recipient sees: an alphanumeric name of up to 11 characters.

bodystring required

The text as it was sent, after typographic quotes and dashes were made SMS-safe.

segmentsinteger required

How many SMS segments the text took. A segment is 160 GSM-7 or 70 UCS-2 characters (153 and 67 when split).

encoding'gsm7' | 'ucs2' | 'null' nullable required

gsm7, or ucs2 when the text has a character outside GSM-7 (an emoji, for example), which makes every segment shorter.

status'queued' | 'sent' | 'delivered' | 'failed' required

queued: accepted. sent: handed to the mobile network. delivered: the phone confirmed it. failed: it did not arrive; see error.

errorstring nullable required

With status failed: a short code, like delivery_failed or sending_failed. Otherwise null.

referencestring nullable required

Your own id for this message, as you sent it (an order number, for example).

created_atstring date-time required

When we accepted the message.

status_updated_atstring date-time nullable required

When the status last changed.

testboolean required

true for a message sent with a test key to a test number. It never reaches a phone.

Changes

No recorded changes to this operation across all 1 revision of this API.