Send Message

Sends a single free-text SMS (e.g. a promotional or informational message) to a Turkmenistan phone number and returns a reference_id for status tracking.

POST/api/v1/messages

X-API-Key

Usage policy. Free-text messaging is granted per account by Ugrat — new accounts start without it; contact us to request access. You must only message recipients who have consented to receive messages from you, and access may be revoked for spam or abuse.

Body parameters

Field	Type	Required	Description
recipient	string	required	E.164 format, +993 followed by 8 digits
body	string	required	Message text, up to 800 characters. Non-Latin text (e.g. Cyrillic) uses 70 characters per SMS segment instead of 160, so long messages are billed as several segments
reference_id	string	optional	Your own UUID for the message; one is generated when omitted. Must be unique within your account — reusing one returns `409 CONFLICT`

Example request

curl -X POST https://api.ugrat.com/api/v1/messages \
  -H "X-API-Key: uk_live_a3f9c2e1..." \
  -H "Content-Type: application/json" \
  -d '{"recipient": "+99361394459", "body": "Ugrat: your order #1042 is ready for pickup."}'

Example response

{
  "success": true,
  "data": {
    "reference_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  }
}

Track delivery with Get Message using the returned reference_id. Supplying your own reference_id makes the request safe to retry: a repeat after a network timeout is answered with 409 CONFLICT instead of sending the message twice.

Errors

Code	Description
400 VALIDATION_FAILED	Invalid recipient (`invalid_phone`), body over 800 characters (`too_long`), or `reference_id` that is not a UUID (`invalid_uuid`) — see `fields`
400 BAD_REQUEST	Malformed JSON
401 UNAUTHORIZED	API key missing or invalid
403 ACCOUNT_PENDING / ACCOUNT_BLOCKED	Account not approved yet, or blocked
403 MESSAGING_NOT_ENABLED	Free-text messaging is not enabled for this account
409 CONFLICT	`reference_id` was already used by your account
429 RATE_LIMITED	Too many requests — retry after `Retry-After`
503 SERVICE_UNAVAILABLE	No delivery route is available right now — retry later