Sending SMS

This guide covers the core mechanics of sending SMS through the Agile Telecom REST API: text encoding, sender IDs, concatenated parts, scheduling and bulk delivery. For the full request/response reference see the SMS API on the wholesale portal.

Encoding: GSM-7 vs Unicode (UCS-2)

SMS messages are encoded in one of two standards. The encoding directly affects how many characters fit into a single part.

Encoding	Per-part limit	Concatenated limit per part	Typical use
GSM-7	160 characters	153 characters	English, Italian, most Latin alphabets
UCS-2	70 characters	67 characters	Emoji, Arabic, Cyrillic, Chinese, Greek

A single non-GSM character (e.g. an emoji or accented vowel outside the GSM extended set) switches the entire message to UCS-2 and reduces the per-part length to 70 characters.

Set enableUnicode: true to allow automatic encoding detection. Set enableConcatenated: true to allow messages longer than one part to be split and reassembled on the handset.

{
  "enableConcatenated": true,
  "enableUnicode": true,
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Hello — your code is 12345. Reply STOP to opt out."
    }
  ]
}

Sender ID

The sender field is the "from" identifier on the recipient handset. Two formats are accepted:

• Numeric — A short code or long number (digits only). Replies are possible if you rent an inbound number.
• Alphanumeric — Up to 11 characters, letters/digits, no spaces. Visible but not replyable. Some countries require pre-registration.

"sender": "Agile"      // alphanumeric (no reply)
"sender": "393351234"  // numeric (replyable if you own the number)

Country regulations

Alphanumeric senders, opt-out keywords and shortcodes are regulated per country. Always check local rules before sending in a new market.

Concatenated (Long) SMS

When a message exceeds the per-part limit, the platform splits it into multiple parts and concatenates them on the device using a UDH (User Data Header). Each part is billed separately.

Encoding	1 part	2 parts	3 parts	4 parts
GSM-7	160	306	459	612
UCS-2	70	134	201	268

Keep enableConcatenated: true unless you have a specific reason to enforce a single part — otherwise long bodies will be rejected.

Scheduling

Send the scheduling field on a message to defer delivery. The format is ISO-like with timezone offset:

{
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Friendly reminder of your appointment tomorrow at 10:00.",
      "scheduling": "2026-05-20 08:30:00.000+0200"
    }
  ]
}

A scheduled message can be cancelled before its dispatch time via the wholesale portal or the cancel endpoint.

Bulk Sending

Send to many destinations in a single API call by adding multiple objects to the messages array, or multiple numbers in destinations.

Same body to many numbers

{
  "enableConcatenated": true,
  "enableDelivery": true,
  "messages": [
    {
      "destinations": [
        "+393351234567",
        "+393351234568",
        "+393351234569"
      ],
      "sender": "Agile",
      "body": "Spring promo: 20% off until Sunday."
    }
  ]
}

Personalized bodies

{
  "enableConcatenated": true,
  "enableDelivery": true,
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Hi Anna, your code is 5571."
    },
    {
      "destinations": ["+393351234568"],
      "sender": "Agile",
      "body": "Hi Marco, your code is 8843."
    }
  ]
}

A single request can carry thousands of destinations. For very large jobs, prefer SMPP for sustained throughput — see the SMPP API reference.

Simulation Mode

Set simulation: true to validate your request end-to-end without actually sending and without consuming credit. The response shape is identical to a real send.

{
  "simulation": true,
  "messages": [ ... ]
}

Tracking IDs

Use the ids field on a message to attach your own per-destination tracking IDs. They are echoed back on submission and delivery reports.

{
  "messages": [
    {
      "destinations": ["+393351234567", "+393351234568"],
      "ids": ["order_5571_a", "order_5571_b"],
      "sender": "Agile",
      "body": "Order confirmed."
    }
  ]
}

Next Steps

• Delivery Reports — Track final delivery state asynchronously.
• Best Practices — Throughput, retries, opt-out compliance.
• Error Handling — Status codes and recovery.
• SMS API reference — Full request/response schema.