Module: Mailkube

Defined in:

lib/mailkube.rb,
lib/mailkube/types.rb,
lib/mailkube/client.rb,
lib/mailkube/config.rb,
lib/mailkube/errors.rb,
lib/mailkube/logging.rb,
lib/mailkube/version.rb,
lib/mailkube/webhooks.rb,
lib/mailkube/transport.rb,
lib/mailkube/events/node.rb,
lib/mailkube/serialization.rb,
lib/mailkube/events/contexts.rb,
lib/mailkube/events/payloads.rb,
lib/mailkube/events/registry.rb,
lib/mailkube/events/envelopes.rb,
lib/mailkube/net_http_adapter.rb,
lib/mailkube/resources/emails.rb,
lib/mailkube/types/scheduled_acks.rb,
lib/mailkube/types/scheduled_emails.rb,
lib/mailkube/resources/scheduled_emails.rb,
lib/mailkube/resources/scheduled_email_requests.rb,
sig/mailkube.rbs,
sig/mailkube/types.rbs,
sig/mailkube/client.rbs,
sig/mailkube/config.rbs,
sig/mailkube/errors.rbs,
sig/mailkube/logging.rbs,
sig/mailkube/webhooks.rbs,
sig/mailkube/transport.rbs,
sig/mailkube/events/node.rbs,
sig/mailkube/serialization.rbs,
sig/mailkube/events/contexts.rbs,
sig/mailkube/events/payloads.rbs,
sig/mailkube/events/registry.rbs,
sig/mailkube/events/envelopes.rbs,
sig/mailkube/net_http_adapter.rbs,
sig/mailkube/resources/emails.rbs,
sig/mailkube/types/scheduled_acks.rbs,
sig/mailkube/types/scheduled_emails.rbs,
sig/mailkube/resources/scheduled_emails.rbs,
sig/mailkube/resources/scheduled_email_requests.rbs

Overview

Signatures for the gem's public surface.

These are checked two ways, and both are needed:

`rbs validate` proves the signatures are internally coherent (every type they name exists).
`steep check`  proves the implementation matches them.

rbs validate alone never loads lib/, so it would happily pass a sig/ describing methods that do not exist, which is the exact drift this directory is here to prevent.

Defined Under Namespace

Modules: ErrorName, Events, Logging, Resources, Serialization, Webhooks, _HeaderMap, _HttpAdapter, _JsonTransport, _LogDevice, _SendTransport Classes: APIError, Attachment, AuthenticationError, BadRequestError, CanceledScheduledEmail, Client, Config, ConfigurationError, ConflictError, ConnectionError, Email, Error, HttpResponse, InvalidRequestError, NetHttpAdapter, NotFoundError, PageSteps, Pagination, RateLimitError, RequestSpec, ScheduledEmail, ScheduledEmailBatchCancel, ScheduledEmailBatchUpdate, ScheduledEmailPage, ServerError, SignatureVerificationError, Tag, Transport

Constant Summary

DEFAULT_BASE_URL =

The API base URL used when nothing else is configured.

Returns:

• (String)

"https://api.mailkube.com/mta/v1/"

STATUS_ERRORS =

Maps an HTTP status to its error class. Any other 5xx is ServerError; the rest APIError.

Returns:

• (Hash[Integer, Class])

{
  400 => BadRequestError,
  403 => AuthenticationError,
  404 => NotFoundError,
  409 => ConflictError,
  422 => InvalidRequestError,
  429 => RateLimitError
}.freeze

VERSION =

The released version of this gem.

This constant is the single source of truth the contract requires: the gemspec reads it (spec.version = Mailkube::VERSION) and the User-Agent reads it, so the version on the wire and the version on rubygems.org cannot disagree.

The value committed here is a permanent 0.0.0 placeholder and is never updated. On release, semantic-release rewrites this line in the release runner just before the gem is built, and commits nothing back to main (see .rules/RELEASE.md). So a checkout reports 0.0.0 and an installed gem reports the real version: that is intended, not a bug to fix by hardcoding one.

Returns:

• (String)

"1.0.0"

Class Method Summary

• .enable_logging(device: $stderr) ⇒ #write

  Turn SDK request logging on.

• .error_class_for(status) ⇒ Class

  Returns the error class for an HTTP status.

• .new(**options) ⇒ Client

  Create a Client.

Class Method Details

.enable_logging(device: $stderr) ⇒ #write

Turn SDK request logging on. Sugar for Mailkube::Logging.enable!.

The device is anything responding to #write(String), so an application passes its own logger rather than being handed one:

Mailkube.enable_logging(device: Rails.logger)

Parameters:

• device (#write) (defaults to: $stderr) —

  where to write; defaults to $stderr.

• device: (_LogDevice) (defaults to: $stderr)

Returns:

• (#write) —

  the device now in use.

# File 'lib/mailkube.rb', line 64

def self.enable_logging(device: $stderr) = Logging.enable!(device: device)

.error_class_for(status) ⇒ Class

Returns the error class for an HTTP status.

Parameters:

• status (Integer) —

  the HTTP status code.

• (Integer)

Returns:

• (Class) —

  the APIError subclass to raise.

# File 'lib/mailkube/errors.rb', line 126

def self.error_class_for(status)
  return STATUS_ERRORS.fetch(status) if STATUS_ERRORS.key?(status)
  return ServerError if status >= 500

  APIError
end

.new(**options) ⇒ Client

Create a Client. Sugar for Mailkube::Client.new, which is what most callers want.

Parameters:

• options (Hash) —

  forwarded verbatim to Mailkube::Client#initialize.

• api_key: (String, nil)
• base_url: (String, nil)
• timeout: (Numeric)
• http: (_HttpAdapter, nil)

Returns:

• (Client) —

  the new client.

# File 'lib/mailkube.rb', line 53

def self.new(**options) = Client.new(**options)