Changelog

The first release of the Ruby gem. It has a method for every one of the 684 methods of the TypeScript SDK, in 53 namespaces, each under its TypeScript name in snake_case, and a parity check in the gem’s own build proves that every one sends byte for byte the request its TypeScript twin sends.

• —Nextmail::Client has a reader for every namespace, from emails, threads and templates to automations, bookings and connected_mailboxes. A request body goes in as keyword arguments or as one Hash whose keys keep the API’s camelCase names, and a response comes back as a Hash with Symbol keys.
• —A client takes api_key: or access_token:, and access_token: also takes anything that responds to call and returns a token, called before every request, so a token renews without a new client. base_url:, timeout:, max_retries:, headers:, user_agent: and adapter: set the rest, and every method takes api_key:, or inbox_token: on temp_mail, to act with another credential for one call.
• —Nextmail.create_client builds a client from NEXTMAIL_API_KEY, NEXTMAIL_ACCESS_TOKEN and NEXTMAIL_BASE_URL, and Nextmail.init, Nextmail.client and Nextmail.reset_client manage one shared client that Nextmail.emails and every other namespace reach through. Nextmail.create_temp_mail opens disposable inboxes with no credential.
• —Every paginated resource has list, which returns one Nextmail::Page with items, has_more? and next_cursor, list_all, which returns every item as an Array, and iterate, which yields each item to a block or returns an Enumerator that fetches the next page only when it gets there.
• —An API refusal raises Nextmail::ApiError or its subclass for the error type, such as NotFoundError, ValidationError or RateLimitError, with status, type, code, param, doc_url, request_id, retry_after_seconds and fields, and predicates such as validation?, step_up_required? and retryable?. No response at all raises Nextmail::NetworkError, with timeout? when the deadline passed, and a mistake in the call itself raises ArgumentError before anything is sent.
• —Reads, sends and every write that is safe to repeat are retried on 408, 500, 502, 503 and 504 with backoff, and on a 429 only when its Retry-After is a minute or less. A send carries an idempotency key that its retries reuse, so a retry never sends a second message. timeout: bounds a whole attempt, and uploads wait at least ten minutes.
• —Nextmail.verify_webhook_signature checks a delivery in constant time, refuses one more than five minutes old and returns the parsed event. It reads the signature from a Hash in any case, a Rack env or Rails’ request.headers.
• —The helpers of the TypeScript SDK are here too, such as Nextmail.to_base64 and Nextmail.resolve_language, and every value set it exports is a frozen Hash on Nextmail, such as Nextmail::WEBHOOK_EVENTS and Nextmail::API_SCOPES.
• —The gem has no runtime dependencies. Requests go through Net::HTTP with a pool of kept-alive connections that one client shares across threads and rebuilds after a fork, and HTTPS_PROXY and NO_PROXY are honoured. client.raw.request reaches any endpoint with the client’s credential and retries, and a credential is never sent over plain http: to anything but this machine.
• —When a newer version is on RubyGems, the client says so once, on a terminal only. disable_update_notice: true or NEXTMAIL_DISABLE_UPDATE_NOTICE=1 turns that off.
• —It needs Ruby 3.2 or newer.