From your first request
to your production integration.

Start with a single message to a number you control and have permission to contact. These examples perform real sends when you supply a valid API key and recipient; there is no simulated-send parameter.

1. Sign in to SMSGenix and select the organisation that will own the integration.
2. Open Developers. An owner or administrator can create an API key with the send:messages scope. Save the secret when it is displayed.
3. Select the shared Testing SMS sender, or an approved sender belonging to that organisation.
4. Check the available welcome credits, eligible bundle allowance or wallet balance.
5. Set SMSGENIX_API_KEY and SMS_RECIPIENT in your backend environment. Run one of the examples below, then retain the returned messageId.

POST https://www.smsgenix.net/api/v1/messages

The documented public API currently sends one message to one recipient per request. Use the authenticated customer portal for contact groups and campaigns.

Send the API key in an HTTP header on every request. Keys begin with sgx_live_, belong to an organisation and carry permissions. A user ID, Google token or Apple token is not required in the SMS request.

Authorization: Bearer YOUR_SMSGENIX_API_KEY
Content-Type: application/json

X-API-Key: YOUR_SMSGENIX_API_KEY is also supported. Use one authentication method consistently. When both are present, a Bearer token takes precedence.

The complete secret is shown only when the key is created. If it is lost, create a replacement. Rotate an exposed key by updating your server to a new key and revoking the old key in the portal. Never place a secret in a URL, browser bundle, mobile application or public repository.

POST /api/v1/messages accepts a JSON object. Use the canonical field names below for new integrations.

Do not send a recipient array. Keep telephone numbers as strings so a leading zero or plus sign is preserved. Personalisation must be resolved by your backend before submitting the message.

Send only one name for each field. The API selects the first non-empty value in the order shown. Do not rely on a projectId request field for isolation or reporting: it is not currently recorded by this send endpoint.

These examples use standard HTTP clients. No SMSGenix SDK installation is required. Replace environment values with your own credentials and recipient; the page contains no real API keys or example telephone numbers.

# Set SMSGENIX_API_KEY and SMS_RECIPIENT in your server environment.
# SMS_RECIPIENT must be a real, consented Sri Lankan mobile number.
curl --request POST 'https://www.smsgenix.net/api/v1/messages' \
  --header "Authorization: Bearer $SMSGENIX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "senderId": "Testing SMS",
  "recipient": "$SMS_RECIPIENT",
  "message": "Your SMSGenix integration test.",
  "messageType": "standard"
}
JSON

A successful request returns HTTP 201 with JSON. The illustrative response below represents a one-segment send covered by free credits, with no wallet funds remaining. Your values will differ.

{
  "success": true,
  "messageId": "00000000-0000-4000-8000-000000000001",
  "serverRef": 123456,
  "senderId": "Testing SMS",
  "recipient": "YOUR_NORMALIZED_RECIPIENT",
  "segments": 1,
  "encoding": "GSM_7",
  "messageType": "standard",
  "costMinor": 0,
  "currency": "LKR",
  "remainingBalanceMinor": 0
}

HTTP 202 with DISPATCH_UNCONFIRMED means the gateway did not confirm the outcome. The response includes a messageId and status: submitted. Do not send again automatically: check message history or contact support. Credits remain reserved until the result is reviewed.

A successful dispatch response is not independent proof of handset delivery. The current API does not return a final delivery receipt or expose a public delivery-status endpoint.

Every organisation can select Testing SMS. New customer accounts receive five free SMS segments once. Those credits are shared within the organisation and can only be spent using that exact sender ID. They are separate from wallet money, and signing in with another linked provider does not create another grant.

For a branded sender, open Sender IDs, submit the requested business details and authorization document, and wait for approval. A sender approved for a different organisation does not authorize your API key to use it.

Sender IDs are case-sensitive. Spaces count toward the eleven-character maximum. Keep spelling, case and spacing identical to the approved record. On a failed dispatch handled by the API, the reserved wallet amount and consumed allowances are restored.

Billing follows segments, not HTTP requests. Encoding is detected automatically from the final text. The presence of a character outside the GSM-7 alphabet switches the message to Unicode.

For example, 161 ordinary GSM-7 characters use two segments. A Unicode message with 71 UTF-16 units also uses two. GSM extension characters such as braces and the euro symbol count as two units; many emoji use two UTF-16 units. Sinhala and Tamil text normally uses Unicode.

Do not estimate cost from visible character count alone. Preview the exact final content in the portal and use the response’s segments and encoding fields for your records. Five free segments may cover fewer than five long messages.

Messages spend from the organisation’s shared resources. Eligible welcome credits apply first for Testing SMS, followed by eligible bundle segments and then wallet funds for uncovered segments. Bundle eligibility depends on validity, destination, message type and encoding. A package may block wallet overage.

costMinor measures the wallet debit for that send, not the amortized purchase price of a bundle. A paid bundle can therefore produce a send response with zero wallet cost. Check current package prices and balances in the portal; do not hard-code a price into your integration.

Top up through Wallet & funding using PayHere. Funds become available after server payment confirmation. There is currently no documented public API for reading the wallet balance or purchasing a package.

{
  "error": "Insufficient wallet balance. Please fund your wallet with PayHere before sending messages.",
  "code": "INSUFFICIENT_FUNDS"
}

Use the HTTP status and stable code field for decisions. Human-readable error text can change. Infrastructure failures may produce a non-JSON response, so your HTTP client should handle that case too.

If the sender is rejected, check the organisation owning the key and the exact approved sender name. If a free test reports insufficient funds, confirm you selected Testing SMS and that enough segments remain for the whole message. If a permission error appears, recreate the key with the sending scope rather than repeatedly retrying.

The current send endpoint does not implement an idempotency-key contract. Adding an Idempotency-Key header does not guarantee deduplication. Every successful new request can send another SMS and incur another charge.

Keep an outbox in your own application. Give each business event a unique ID, prevent concurrent workers from submitting the same event, and record the returned message ID. A network timeout may happen after dispatch: mark its outcome as unknown and review message history before deciding whether to resend.

Fix validation and authentication errors before retrying. For service interruptions, pause your queue and investigate. There is no published per-second throughput guarantee; coordinate sustained production volumes with support and use a bounded worker queue.

For an application-managed audience, send one request per consented recipient. Deduplicate and normalize your list before enqueueing it, limit concurrency and record each result separately. Some recipients may succeed while others fail; a list of separate requests is not an atomic batch.

For contact imports, groups, campaigns and scheduling, use the customer portal. The public v1 contract currently has no bulk campaign endpoint, scheduled-send field, message lookup endpoint, balance endpoint or customer delivery webhook subscription. Do not integrate against internal /api/workspace/* routes: they require a browser session and are not the public API contract.

Use message history in the portal for operational review. If your application requires verified final delivery receipts, inbound replies or automated status callbacks, discuss that requirement with support before depending on it.

• Store API keys in your server’s environment or a secrets manager; keep them out of client code and logs.
• Create a separate key for each integration and grant only the scopes it needs.
• Send over HTTPS to the canonical www.smsgenix.net endpoint.
• Validate recipients, maintain consent records and honor opt-outs in your application before every send.
• Log your event ID, response code, message ID and segment count. Mask telephone numbers and avoid logging message bodies containing private information.
• Protect any public form that triggers SMS with your own authentication, validation and abuse controls.
• Verify one controlled send and its charge before enabling a larger audience.
• Monitor failures and remaining resources; pause sending when credentials, sender approval or funds need attention.

Changing only the API key is not enough. Compare the previous API with this contract and update your server integration deliberately.

Test standard text, Sinhala or Tamil content, a long multipart message and a controlled validation failure. Compare expected segment counts and wallet changes, then move production traffic gradually.