Elixir / Phoenix

Installation

Add to `mix.exs`

defp deps do
  [
    {:keplars, "~> 1.10"}
  ]
end

Then run:

mix deps.get

Set your API key

export KEPLARS_API_KEY=kms_your_workspace_id.live_your_secret

Or in config/runtime.exs:

config :keplars, api_key: System.fetch_env!("KEPLARS_API_KEY")

Send your first email

{:ok, client} = Keplars.new(System.get_env("KEPLARS_API_KEY"))

{:ok, response} = Keplars.Emails.send_instant(client, %{
  to:      "[email protected]",
  from:    "[email protected]",
  subject: "Hello!",
  body:    "<h1>It works!</h1>",
  is_html: true
})

IO.inspect(response.id)

Priority Levels

Function	Delivery	Use case
`send_instant`	0–5 seconds	OTP, 2FA, password reset
`send_high`	0–30 seconds	Transactional confirmations
`send_async` / `send`	0–5 minutes	Welcome emails, notifications
`send_bulk`	Background	Newsletters, campaigns

Keplars.Emails.send_instant(client, params)
Keplars.Emails.send_high(client, params)
Keplars.Emails.send_async(client, params)
Keplars.Emails.send_bulk(client, params)

Using Templates

{:ok, response} = Keplars.Emails.send_instant(client, %{
  to:          "[email protected]",
  from:        "[email protected]",
  template_id: "your-template-id",
  params: %{
    user_name:         "Jane",
    verification_code: "123456"
  }
})

Schedule an Email

{:ok, response} = Keplars.Emails.schedule(client, %{
  to:            "[email protected]",
  from:          "[email protected]",
  subject:       "Weekly digest",
  body:          "<p>Here is your digest.</p>",
  is_html:       true,
  scheduled_for: "2026-02-01T09:00:00Z",
  timezone:      "America/New_York"
})

Error Handling

case Keplars.Emails.send_instant(client, params) do
  {:ok, response} ->
    IO.inspect(response.id)

  {:error, %Keplars.Error{code: :authentication_error}} ->
    IO.puts("Invalid API key")

  {:error, %Keplars.Error{code: :rate_limit_exceeded, retry_after: retry_after}} ->
    IO.puts("Rate limit hit, retry after: #{retry_after}")

  {:error, %Keplars.Error{code: :domain_not_verified}} ->
    IO.puts("Sending domain not verified")

  {:error, error} ->
    IO.inspect(error)
end

Phoenix Integration

Add a mailer module to your Phoenix app:

defmodule MyApp.Mailer do
  def client do
    {:ok, client} = Keplars.new(Application.fetch_env!(:my_app, :keplars_api_key))
    client
  end

  def send_welcome(email) do
    Keplars.Emails.send_instant(client(), %{
      to:      email,
      from:    "[email protected]",
      subject: "Welcome to MyApp!",
      body:    "<h1>Welcome!</h1>",
      is_html: true
    })
  end
end

Admin API

Need to manage contacts, audiences, automations, or domains? Use an admin key - same client, different key suffix:

{:ok, client} = Keplars.new("kms_xxx.adm_xxx")

Keplars.Contacts.add(client, %{email: "[email protected]", name: "Jane"})
Keplars.Audiences.create(client, %{name: "Newsletter"})
Keplars.Automations.enroll(client, "auto_id", "[email protected]")
Keplars.Domains.verify(client, "domain_id")

See the full Admin API reference.

Next Steps

Admin API - Contacts, audiences, automations, domains
Send Emails - API reference
Email Templates - Build reusable templates
Schedule Emails - Delayed delivery

Elixir / Phoenix

On this page