# `Unicom360.SMS`
[🔗](https://github.com/TechRode-Solution-Limited/unicom360-elixir/blob/v0.1.0/lib/unicom360/sms.ex#L1)

Send SMS (`POST /api/v1/json/bulk/sms`).

    {:ok, result} =
      Unicom360.SMS.send(client, %{
        from: "Unicom360",
        to: ["260971234567", "260961234567"],
        message: "Your verification code is 482193. It expires in 5 minutes."
      })

    for recipient <- result.results do
      IO.puts("#{recipient.mobile_number} #{recipient.status} #{recipient.message_id}")
    end

The gateway accepts GSM-7 text only, at most 1,200 characters, and bills
`max(1, ceil(length / 160))` units per recipient. The SDK does not check this itself; see
`Unicom360.GSM` to check before sending.

# `params`

```elixir
@type params() ::
  %{
    :from =&gt; String.t(),
    :to =&gt; String.t() | [String.t()],
    :message =&gt; String.t(),
    optional(:user_reference_id) =&gt; String.t() | nil,
    optional(:callback_url) =&gt; String.t() | nil,
    optional(:source) =&gt; String.t() | nil
  }
  | keyword()
```

The SMS parameters, as a map or a keyword list:

  * `:from` (required) - a registered sender ID.
  * `:to` (required) - one number, or a list of numbers. International form (`"2609..."`).
  * `:message` (required) - the text.
  * `:user_reference_id` - your reference. Makes the send safe to retry, and lets the gateway
    refuse a repeat (`DUPLICATE_REFERENCE`).
  * `:callback_url` - where the gateway posts delivery reports (unsigned; see
    `Unicom360.Webhook.parse_sms_callback/1`).
  * `:source` - a label for your reporting.

# `send`

```elixir
@spec send(Unicom360.Client.t(), params(), keyword()) ::
  {:ok, Unicom360.SMS.SendResult.t()} | {:error, Unicom360.Error.t()}
```

Sends an SMS to one or more numbers.

Returns `{:ok, %Unicom360.SMS.SendResult{}}`, whose `results` hold one entry per recipient. An
invalid number among them is not an error: its entry's status is `"Invalid mobile number"`
(see `Unicom360.SMS.SendResult.invalid/1`). **Results are not in request order past the
tenth recipient**: find one with `Unicom360.SMS.SendResult.by_number/2`.

Fails with `{:error, %Unicom360.Error{}}`: for example `code: "INVALID_SENDER_ID"` or
`"INSUFFICIENT_BUNDLE"` (an `:api_error` on HTTP 200).

Options: `:timeout` (ms per attempt) and `:max_retries` override the client's for this call.
The send is retried after a failure that may have reached the gateway only when it has a
`user_reference_id`.

# `send!`

```elixir
@spec send!(Unicom360.Client.t(), params(), keyword()) :: Unicom360.SMS.SendResult.t()
```

Like `send/3`, but returns the result or raises `Unicom360.Error`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*