Helpers and constants
What else the gem defines besides the client.
Module methods
| Method | What it is |
|---|---|
| OpenEmail.init, OpenEmail.client | Configure the shared client once, then reach it from anywhere. It builds itself from OPENEMAIL_API_KEY if init never ran. |
| OpenEmail.emails, OpenEmail.threads and every other namespace | Shortcuts to the namespaces of the shared client. |
| OpenEmail.reset_client | Drops the shared client, so the next call builds a fresh one, which is what a test wants between cases. |
| OpenEmail.create_client, OpenEmail::Client.new, OpenEmail.new | A separate client. create_client reads the environment for anything you leave out, and Client.new (or OpenEmail.new) takes only what you pass. |
| OpenEmail.create_temp_mail | A disposable-inbox client that carries no API key. |
| OpenEmail.verify_webhook_signature | Checks a delivery’s signature in constant time, with a replay window. Returns the parsed event, and raises OpenEmail::WebhookSignatureError on any failure. |
| OpenEmail.to_base64 | Base64 for attachment bytes, from a binary String, an IO or a Pathname. |
| OpenEmail.api_key? | Whether a String has the oe_live_ or oe_test_ shape. A shape check, not proof the key still works. |
| OpenEmail.access_token? | Whether a String has the shape of an OAuth access token: 1 to 512 characters, not beginning oe_. |
| OpenEmail.sealed? | Whether a message’s body is ciphertext. It is false for the two signed formats, whose bodies arrived in the clear. |
| OpenEmail.resolve_language, OpenEmail.language_by_code, OpenEmail.rtl_language? | The lookups a language picker needs, over the bundled OpenEmail::LANGUAGES table. |
Constants
Every value set the TypeScript SDK exports is a frozen Hash on OpenEmail, keyed by the same names, so OpenEmail::WEBHOOK_EVENTS[:EMAIL_DELIVERED] is "email.delivered". Use .values where you need the list, and .value? to check a value that came from outside.
events = OpenEmail::WEBHOOK_EVENTS.values scopes = [OpenEmail::API_SCOPES[:EMAILS_SEND], OpenEmail::API_SCOPES[:THREADS_READ]] puts events.size, scopes.join(","), OpenEmail::PAGE_LIMITS[:MAX_LIMIT]| Constant | What it holds |
|---|---|
| OpenEmail::VERSION | The gem version. |
| OpenEmail::API_SCOPES | The scope vocabulary, for a key-creation screen. |
| OpenEmail::WEBHOOK_EVENTS, OpenEmail::WEBHOOK_SIGNATURE_HEADERS | The events an endpoint can subscribe to, and the names of the headers a delivery carries. |
| OpenEmail::ERROR_TYPES | The error vocabulary that ApiError#type takes. |
| OpenEmail::PAGE_LIMITS | The largest and the default limit: on most paged lists: 100 and 25. A few lists take more, and each method’s reference says so. |
| OpenEmail::RULE_FIELDS, OpenEmail::RULE_OPERATORS, OpenEmail::RULE_ACTIONS | The vocabulary a rule’s conditions and actions are built from. |
| OpenEmail::MESSAGE_ENCRYPTION_FORMATS | The five envelopes ingest can name. Three of them are sealed. |
| OpenEmail::CREDENTIAL_KINDS, OpenEmail::STEP_UP_METHODS, OpenEmail::STEP_UP_ERROR_CODES | Which credential me.get and me.ping describe, how a verification code is checked, and the codes a verification can fail with. |
| OpenEmail::THREAD_SORTS, OpenEmail::PEOPLE_SORTS, OpenEmail::FILE_SORTS and the other *_SORTS | The orders a list can be sorted in. |
| OpenEmail::FORM_STATUSES, OpenEmail::BROADCAST_STATUSES, OpenEmail::SUPPRESSION_REASONS and the other sets | The values a field of a resource can take. Each set is named after what it holds. |
Objects
A response is the parsed JSON as a Hash with Symbol keys. The gem builds an object of its own only where it shapes the answer, and each is an immutable Data.
| Class | What it carries |
|---|---|
| OpenEmail::Page | items, has_more? and next_cursor, from every paged list. |
| OpenEmail::PeoplePage | The same plus seen, from contacts.list_people. |
| OpenEmail::TempMessagesPage | The same plus expires_at, from temp_mail.list_messages. |
| OpenEmail::AddressBookPage, OpenEmail::AddressBook | unrestricted, addresses and domains, from addresses.list (with has_more? and next_cursor) and addresses.list_all. |
| OpenEmail::BatchResult | items, sent and failed, from emails.send_batch. |
| OpenEmail::TemplateSends | items, total, page and page_size, from templates.list_sends. |
| OpenEmail::HttpRequest, OpenEmail::HttpResponse | What an adapter: receives and returns. A request prints its Authorization header as [redacted]. |
Every error the gem raises on purpose inherits from OpenEmail::Error: ApiError and its subclasses, NetworkError and WebhookSignatureError. A wrong argument is an ArgumentError instead, because it is a mistake in the calling code rather than something to rescue.
An endpoint this does not wrap yet
A gem release should never be what stands between you and an endpoint that already works. client.raw.request takes a path and keyword options and returns the parsed body, with the client’s credential, base URL, timeout and retry policy applied.
result = client.raw.request( "/something-new", method: :post, query: {dryRun: true}, body: {name: "Invoices"}, repeatable: true) p resultA GET is retried like any other read. Any other method is sent once unless you pass repeatable: true, which is your assertion that it may be sent twice. query: skips values that are nil or empty, and api_key: works as it does on every other method.
What it deliberately does not do
- It validates no request body. The server’s schema is the only copy of the rules, and a second copy here would eventually refuse an address a newer server accepts, in a version somebody pinned two years ago.
- It has no runtime dependencies, not even a JSON or HTTP gem beyond the standard library.
- It reshapes a response in one way only: a collection’s
dataarray is lifted out of its envelope into one of the objects above. Every other response comes back as the API sent it, with the API’s camelCase keys.
The gem’s parity check keeps this honest. It fails the build when a TypeScript method has no Ruby twin, takes different options, or sends a different request.