Guides

Send Your First SMS

Fund account in Portal.

Obtain approved sender ID in Portal.

Create SMS API key in Portal.

Call POST /messages/send.

Store message UUID.

Call GET /messages/status/{messageId}.

Complete the Portal setup.
Send one short ASCII message to a test recipient you control.
Confirm HTTP 202 and store data.messageId.
Poll status until DELIVERED or FAILED.
Compare the returned credit effect with the Portal account activity.

Choose A Send Method

Situation	Use	Tradeoff
One recipient	`/send`	Simplest request and returns one UUID
Many recipients, same content	`/batch`	Compact request, but no per-message UUIDs in response
Personalized content	`/send-bulk`	Returns one result and UUID per accepted message
Scheduled delivery	`/send-bulk`	One ISO schedule applies to the complete request
Per-recipient result handling	`/send-bulk`	Exposes accepted/rejected counts and results

Schedule And Track Messages

Generate personalized content before calling the API.
Calculate likely segments for each rendered message.
Send scheduledAt with an explicit UTC offset or Z.
Store every returned message UUID.
Poll after the scheduled time.
Stop on DELIVERED or FAILED.

The API validates ISO date-time syntax but does not reject a timestamp in the past. Validate schedule time in your application.

Setup Versus API Usage

Action	Owner
Add credits	Portal
Request or manage sender ID	Portal
Create, rotate, or revoke API key	Portal
Send messages	Developer API
Retrieve one message status	Developer API
Review account-wide activity and balance	Portal

Do not use Portal session credentials in application API calls.

Common Integration Mistakes

Wrong Authentication

Use:

Authorization: Bearer ntfy_your_api_key

Do not use a Portal JWT or a custom API-key header.

Wrong Message Identifier

Store the UUID returned by /send or /send-bulk. Numeric IDs and sender IDs are not message IDs.

Unapproved Sender

Confirm sender approval in the Portal. A sender name existing in your records does not make it sendable.

Invalid Recipient Format

Compatibility requests can omit +; canonical requests require E.164 with +. Confirm destination-country availability before sending.

Underestimating Credits

Credits follow segments for every eligible recipient. Non-ASCII and long content consume more segments.

Losing Batch Correlation

/batch does not return per-message UUIDs. Use /send-bulk when delivery tracking must correlate each recipient.

Unsafe Retries

SMS send requests have no public idempotency key. An automatic retry can create another message and another debit. Reconcile an uncertain response before retrying.

Expecting SMS Webhooks

The current SMS Developer API exposes status polling, not callback registration. WABA webhook documentation does not apply to SMS.

On this page