Configuration

These raise ArgumentError from the line that had the wrong value in it, rather than surfacing as a confusing failure on your first send. The message says what was wrong and what to pass instead, and it never repeats a credential.

Build the client once and share it. A fresh client per request discards its open connections for nothing, and none of the state on it is per caller. A client is frozen once it is built and is safe to use from many threads at once, so a Puma or Sidekiq process needs only one, and after a fork the child opens connections of its own.

For the case that would otherwise force one client per key, such as a job sending on behalf of several workspaces, pass api_key: on the call. It replaces the Authorization header for that request and leaves nothing behind on the client.

message = {from: "[email protected]", to: "[email protected]", subject: "Your invoice", text: "Attached."}workspace_key = ENV.fetch("OPENEMAIL_API_KEY") client.emails.send(message) client.emails.send(message, api_key: workspace_key) client.threads.list(folder: "inbox", api_key: workspace_key)client.webhooks.list(api_key: workspace_key)

Every method outside temp_mail takes it as a keyword argument, beside the filters on a list, and the temp_mail methods take inbox_token: instead. It is checked before the request is sent, by the same rule the client uses, so a typo raises an ArgumentError about the api_key passed to this call rather than a 401 about a credential you then have to go and find. A retried call keeps the key it was given.

client.raw is the transport every method goes through. client.raw.request calls a path no method wraps yet, with the client’s credential, base URL, timeout and retry policy applied, and returns the parsed body the way a method does.

ping = client.raw.request("/ping") label = client.raw.request("/labels", method: :post, body: {name: "Invoices"}) p ping[:ok], label[:id]

OpenEmail.create_temp_mail builds a client for disposable inboxes that carries no API key and reads none from the environment. It creates inboxes anonymously, and each read sends the inbox token that create returned, or the newer one extend returned, either per call as inbox_token: or once as OpenEmail.create_temp_mail(inbox_token:).

temp_mail = OpenEmail.create_temp_mail inbox = temp_mail.createpage = temp_mail.list_messages(inbox[:id], inbox_token: inbox[:token]) p page.items.size, page.expires_at

An app a person connected over OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as access_token:, either the token itself, or anything that responds to call and returns it, such as a lambda or a Method. It is called once for every call, and that call’s retries reuse what it returned, so renew the token inside it when it is close to expiring and the client never has to be rebuilt.

tokens = {current: "token-from-your-oauth-flow"} oauth_client = OpenEmail::Client.new(access_token: -> { tokens.fetch(:current) }) me = oauth_client.me.get puts me[:clientId], me[:expiresAt] if me[:object] == "oauth_token"

Before a sensitive change, such as deleting a domain or changing a webhook, the API asks an access token for the verification code the web app would ask the person for. The call raises an OpenEmail::PermissionError, a 403 whose step_up_required? is true, and nothing was changed. Ask for a code, verify the one the person gives you, then make the call again. An API key is never asked.

domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" begin  client.domains.delete(domain_id)rescue OpenEmail::ApiError => error  raise unless error.step_up_required?   challenge = client.security.begin_step_up   if challenge[:method] == "email"    puts "Enter the code we emailed to #{challenge[:sentTo]}"  else    puts "Enter the code from your authenticator app, or a backup code"  end   client.security.verify_step_up(code: $stdin.gets.to_s.strip)  client.domains.delete(domain_id)end

When a newer version of the gem is on RubyGems, the client says so once per process, on standard error, as a line such as ℹ openemail 0.0.2 is available, you are on 0.0.1. followed by the gem’s page. The check runs when the first client is built, in a background thread with a two second timeout, only when standard output is a terminal, and a failure to reach RubyGems is ignored.

The default adapter finds its proxy with Ruby’s own URI#find_proxy, so it follows the same rules as the rest of the standard library: https_proxy or HTTPS_PROXY names the proxy, and no_proxy or NO_PROXY lists the hosts that go direct. A user name and password in the proxy URL are sent to the proxy, and a server on this machine is never reached through one.

adapter: replaces the HTTP layer. It is anything that responds to call(request), a lambda included, and returns an OpenEmail::HttpResponse with status, headers and body. The request is an OpenEmail::HttpRequest with method, url, headers, body and timeout, so a test can check exactly what would have gone out.

requests = [] adapter = lambda do |request|  requests << request  OpenEmail::HttpResponse.new(    status: 200,    headers: {"content-type" => "application/json"},    body: JSON.generate({id: "msg_test", status: "sent", replayed: false})  )end test_client = OpenEmail::Client.new(api_key: "oe_test_fake", adapter:, max_retries: 0, disable_update_notice: true) sent = test_client.emails.send(from: "[email protected]", to: "[email protected]", subject: "Hi", text: "Hello") p sent[:status], requests.first.method, requests.first.url, requests.first.headers["Idempotency-Key"]p requests.first

Printing a request shows its Authorization header as [redacted], so a test log never holds the key.

• —Return a status outside 2xx with the API’s error envelope as the body, such as {"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}, to get the matching OpenEmail::ApiError subclass.
• —Raise Timeout::Error from call, or Net::ReadTimeout, which is one, to get an OpenEmail::NetworkError whose timeout? is true. Any other StandardError, such as Errno::ECONNREFUSED, becomes a NetworkError whose timeout? is false.
• —NameError, TypeError and ArgumentError raised inside the adapter count as bugs in it. They are raised unchanged and never retried.