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

Send email (`POST /api/v1/json/bulk/email`).

    {:ok, result} =
      Unicom360.Email.send(client, %{
        from: "noreply@yourdomain.com",
        to: ["jane@example.com", "john@example.com"],
        subject: "Your order is confirmed",
        email_body: "<p>Thanks for your order. Order ZM4821 is confirmed.</p>",
        reply_to: "support@yourdomain.com"
      })

    jane = Unicom360.Email.SendResult.by_address(result, "jane@example.com")

**Email is never retried after the request may have reached the gateway**, even with a
`user_reference_id`: the gateway's duplicate check for email is not atomic, so two
overlapping attempts could both be sent. It is retried only after a 429 and after a failure to
connect.

# `params`

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

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

  * `:from` (required) - a registered sender address.
  * `:to` (required) - one address, or a list of addresses.
  * `:subject` (required).
  * `:email_body` (required) - HTML or plain text.
  * `:reply_to` - the Reply-To address.
  * `:user_reference_id` - your reference; the gateway refuses a later repeat of it
    (`DUPLICATE_REFERENCE`).
  * `:callback_url` - where the gateway posts delivery reports (unsigned; see
    `Unicom360.Webhook.parse_email_callback/1`).
  * `:source` - a label for your reporting.

# `send`

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

Sends an email to one or more addresses.

Returns `{:ok, %Unicom360.Email.SendResult{}}`, one entry per recipient. An invalid address is
not an error: its entry's status is `"Invalid email address"`. **Results are not in request
order past the tenth recipient**: find one with `Unicom360.Email.SendResult.by_address/2`.

Options: `:timeout` (ms per attempt) and `:max_retries`.

# `send!`

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

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

---

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