Skip to content
Aureus PrimeDocs

Guides

Best practices

Never debit twice

After a network outage, you do not know whether your request got through. Send it again with the same Idempotency-Key (for example the order identifier): if it had got through, you receive the same message, without a new debit.

One-time codes

Send them with "sensitive": true: their text is erased as soon as they are sent and is never stored. Do not schedule them.

Retries

  • 5xx or timeout: retry with the same Idempotency-Key, spacing out the attempts (for example 1 s, 5 s, 30 s). The number of attempts and the acceptable wait depend on your use case.
  • 429: wait for the number of seconds given by Retry-After, then retry with the same Idempotency-Key.
  • 4xx: do not retry as is; fix the request (see Errors).

Configuration

Make the API base URL and the sender configurable, without changing the code. As long as your sender name is not approved, do not send senderId: the shared sender is used. A name not yet approved causes every request to be rejected (422 SENDER_NOT_APPROVED).

Security

  • API key on the server side only; never in a mobile app or a web page.
  • Two active keys at most: use the second one to change keys without downtime.
  • Numbers are masked in every response. Rather, link the message id to your business object (order, notification); only keep a mapping to the number if you have a real use for it, and no longer than necessary.

Permitted SMS

The API is for transactional SMS: codes, confirmations, reminders, alerts linked to a service the recipient uses. Marketing and unsolicited messages are prohibited by the terms of use.

Text

160 characters per SMS, in the SMS alphabet: your text is always converted to it (ê becomes e, the curly apostrophe becomes straight, emoji are removed). Write it that way directly to know exactly what is sent, and check normalized in the response. Prefer a short, clear text, with your company name if it does not appear in the sender. A really long message: "allowTwoParts": true, billed as 2 SMS.

Sending to your customers before verification

Until your identity or business is verified, only the test SMS to your own verified number goes through. Have your account verified before integrating the API in production.