Nuntly

Copy Markdown View Source

CI Hex.pm Documentation

A compact Req-backed Elixir client for the Nuntly REST API

Nuntly is generated from the API's OpenAPI document and supports both configured, Repo-style modules and explicit clients.

Configured module API

For the common case where an application has one stable configuration, define a Repo-style module:

defmodule MyApp.Nuntly do
  use Nuntly, otp_app: :my_app
end

Configure it using the module as the application environment key:

# config/runtime.exs
config :my_app, MyApp.Nuntly,
  api_key: System.fetch_env!("NUNTLY_API_KEY")

All operations are then available directly, without a client argument:

{:ok, response} =
  MyApp.Nuntly.send_email(%{
    from: "hello@example.com",
    to: "person@example.net",
    subject: "Hello",
    text: "Sent from Elixir"
  })

MyApp.Nuntly.list_messages(%{"domainId" => domain_id, limit: 25})

client/0 is overridable when an application needs custom credential lookup or test behavior.

Explicit client API

Use the resource modules directly when configuration varies by request or tenant:

client = Nuntly.new(api_key: tenant.api_key)

Nuntly.Emails.send_email(client, payload,
  headers: [{"idempotency-key", idempotency_key}]
)

Nuntly.new/1 also reads NUNTLY_API_KEY when :api_key is omitted. Other client options are passed to Req.new/1:

client = Nuntly.new(receive_timeout: 10_000, retry: :transient)

Both APIs follow the same conventions:

  • Path values are positional arguments and are URL-escaped.
  • JSON payloads are plain maps passed as body.
  • Query strings are plain maps passed as params.
  • The final keyword list is passed to Req, allowing headers and other per-request options.

The explicit resource API additionally takes the client as its first argument. Map keys are forwarded unchanged. For camel-cased API fields, use their exact OpenAPI spelling, usually as strings.

Req returns {:ok, %Req.Response{}} for HTTP responses, including non-2xx statuses, and {:error, exception} for transport failures.

See the generated API reference for every function, argument, request field, HTTP path, and examples for both calling styles.

The generated API modules are:

Regenerating

The Bun generator lives in the generator/ directory:

cd generator
bun install
bun test
bun run generate
cd ..
mix test

See generator/README.md for its design, options, and coverage commands. Generated Elixir source is kept in lib/nuntly/generated/, and the generated Markdown reference is written to docs/rest-api-reference.md. Custom code should live outside generated files.

Installation

Add nuntly to your dependencies:

def deps do
  [
    {:nuntly, "~> 0.1.0"}
  ]
end