# Keplars Elixir SDK

Official Elixir SDK for the [Keplars](https://keplars.com) transactional email API.

## Installation

Add `keplars` to your dependencies in `mix.exs`:

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

## Configuration

Set your API key via environment variable:

```bash
export KEPLARS_API_KEY="kms_your_key_id.live_your_secret"
```

Or pass it directly when creating the client.

## Usage

```elixir
{: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

```elixir
{: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

```elixir
{: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

```elixir
{: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

```elixir
{: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

```elixir
{: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

```elixir
{: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{}}`:

```elixir
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

- [Elixir Examples](https://github.com/KeplarsHQ/elixir-examples) — Phoenix app with transactional emails, bulk newsletter, scheduling, and webhook verification
- [Kotlin Examples](https://github.com/KeplarsHQ/kotlin-examples) — Ktor + coroutines
- [Java Examples](https://github.com/KeplarsHQ/java-examples) — Spring Boot + CompletableFuture

## License

MIT