Keplars Elixir SDK

Official Elixir SDK for the Keplars transactional email API.

Installation

Add keplars to your dependencies in mix.exs:

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

Configuration

Set your API key via environment variable:

export KEPLARS_API_KEY="kms_your_key_id.live_your_secret"

Or pass it directly when creating the client.

Usage

{:ok, client} = Keplars.new("kms_your_key_id.live_your_secret")

{:ok, resp} = Keplars.Emails.send(client, %{
  to: "user@example.com",
  from: "noreply@yourdomain.com",
  subject: "Welcome!",
  html: "<h1>Hi there!</h1>"
})

Priority-based sending

{:ok, _} = Keplars.Emails.send_instant(client, params)
{:ok, _} = Keplars.Emails.send_high(client, params)
{:ok, _} = Keplars.Emails.send_async(client, params)
{:ok, _} = Keplars.Emails.send_bulk(client, params)

Scheduling

{:ok, _} = Keplars.Emails.schedule(client, %{
  to: "user@example.com",
  from: "noreply@yourdomain.com",
  subject: "Scheduled email",
  html: "<h1>Hello</h1>",
  scheduled_for: "2026-12-01T10:00:00Z"
})

Contacts

{:ok, _} = Keplars.Contacts.add(client, %{email: "user@example.com", name: "User"})
{:ok, _} = Keplars.Contacts.get(client, "user@example.com")
{:ok, _} = Keplars.Contacts.list(client, audience_id: "aud_123", page: 1, limit: 20)
{:ok, _} = Keplars.Contacts.update(client, "user@example.com", %{name: "New Name"})
{:ok, _} = Keplars.Contacts.delete(client, "user@example.com")

Audiences

{:ok, _} = Keplars.Audiences.create(client, "My Audience", "Description")
{:ok, _} = Keplars.Audiences.list(client)
{:ok, _} = Keplars.Audiences.get(client, "aud_123")
{:ok, _} = Keplars.Audiences.delete(client, "aud_123")

Automations

{:ok, _} = Keplars.Automations.list(client)
{:ok, _} = Keplars.Automations.get(client, "auto_123")
{:ok, _} = Keplars.Automations.enroll(client, "auto_123", "user@example.com")
{:ok, _} = Keplars.Automations.unenroll(client, "auto_123", "user@example.com")

Domains

{:ok, _} = Keplars.Domains.add(client, "yourdomain.com")
{:ok, _} = Keplars.Domains.list(client)
{:ok, _} = Keplars.Domains.get_status(client, "dom_123")
{:ok, _} = Keplars.Domains.verify(client, "dom_123")
{:ok, _} = Keplars.Domains.delete(client, "dom_123")
{:ok, _} = Keplars.Domains.create_api_key(client, %{domain_id: "dom_123", name: "My Key"})

Error Handling

All functions return {:ok, result} or {:error, %Keplars.Error{}}:

case Keplars.Emails.send(client, params) do
  {:ok, %{data: data}} ->
    IO.inspect(data)
  {:error, %Keplars.Error{code: :authentication_error}} ->
    IO.puts("Invalid API key")
  {:error, %Keplars.Error{code: :rate_limit_exceeded, retry_after: seconds}} ->
    IO.puts("Rate limited. Retry after #{seconds}s")
  {:error, %Keplars.Error{message: msg}} ->
    IO.puts("Error: #{msg}")
end

Error codes: :validation_error, :authentication_error, :authorization_error, :domain_not_verified, :rate_limit_exceeded, :not_found, :conflict, :internal_error, :network_error

Example Projects

License

MIT