MailKite.Client (MailKite v0.13.0)

Copy Markdown View Source

The MailKite API client.

A client is a plain struct holding a Bearer credential and the API base URL. Build one with new/1 or new/2 and pass it to the functions in MailKite.Methods (or call request/4 directly).

mk = MailKite.Client.new(System.get_env("MAILKITE_API_KEY"))
{:ok, res} = MailKite.Methods.send(mk, %{
  "from" => "hello@app.mailkite.dev",
  "to" => "ada@example.com",
  "subject" => "Hi",
  "text" => "It works."
})

The credential is always a Bearer token, so an OAuth access token works anywhere an API key (mk_live_…) does. For short-lived OAuth tokens, pass a :get_token zero-arity function — it is called before every request to fetch a fresh token.

Summary

Types

t()

A MailKite API client.

Functions

new(token)

Build a client.

new(token, base_url)

Build a client from a token and a custom base URL.

page_query(opts)

Build the pagination query string for a list endpoint from a keyword list of :before / :limit / :search options. Returns "" when none are set, or "?before=…&limit=…&search=…" (URL-encoded, only the keys that are set).

request(client, method, path, body \\ nil)

The low-level request. Every function in MailKite.Methods is a one-liner on top of it. Returns {:ok, value} for a 2xx response (the parsed JSON body, or nil when empty) or {:error, %MailKite.Error{}} otherwise.

upload_attachment(client, file)

Upload a file and get back a secure, time-limited URL to reference as a send/2 attachment (%{"filename" => …, "url" => …}) instead of base64-inlining large files on every send.

Types

t()

@type t() :: %MailKite.Client{
  base_url: String.t(),
  get_token: (-> String.t()) | nil,
  token: String.t() | nil
}

A MailKite API client.

Functions

new(token)

@spec new(String.t() | keyword() | map()) :: t()

Build a client.

Accepts either a Bearer credential string (an API key mk_live_… or an OAuth access token), or a keyword list / map with:

  • :access_token — a static OAuth access token (alias for the token arg).
  • :get_token — a zero-arity function called before each request to fetch a fresh Bearer token (use with short-lived OAuth access tokens).
  • :base_url — override the API base URL (default https://api.mailkite.dev).

new(token, base_url)

@spec new(String.t(), String.t()) :: t()

Build a client from a token and a custom base URL.

page_query(opts)

@spec page_query(keyword() | map()) :: String.t()

Build the pagination query string for a list endpoint from a keyword list of :before / :limit / :search options. Returns "" when none are set, or "?before=…&limit=…&search=…" (URL-encoded, only the keys that are set).

request(client, method, path, body \\ nil)

@spec request(t(), String.t(), String.t(), any()) ::
  {:ok, any()} | {:error, MailKite.Error.t()}

The low-level request. Every function in MailKite.Methods is a one-liner on top of it. Returns {:ok, value} for a 2xx response (the parsed JSON body, or nil when empty) or {:error, %MailKite.Error{}} otherwise.

upload_attachment(client, file)

@spec upload_attachment(t(), map()) :: {:ok, any()} | {:error, MailKite.Error.t()}

Upload a file and get back a secure, time-limited URL to reference as a send/2 attachment (%{"filename" => …, "url" => …}) instead of base64-inlining large files on every send.

Provide the file ONE of four ways (checked in this order):

  • "url" — MailKite fetches and re-hosts the file (JSON body).
  • "bytes" — raw binary uploaded directly.
  • "path" — a local file path, read off disk and uploaded as raw binary.
  • "content" — base64 content (JSON body).

Optional "filename", "contentType", and "retentionDays" apply to all modes. Keys may be strings or atoms.