Class: Mailkube::Resources::Emails

Inherits:
Object
  • Object
show all
Defined in:
lib/mailkube/resources/emails.rb,
sig/mailkube/resources/emails.rbs

Overview

The emails namespace, reached as client.emails.

This is the worked example every new resource copies. Note what it does not do: it holds no configuration, performs no I/O, and never requires net/http. It depends only on an object responding to the one verb it calls.

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ Emails

Returns a new instance of Emails.

Parameters:

  • transport (#send_email) —

    the transport performing this resource's requests.

  • (_SendTransport) 


12
13
14
15
 
# File 'lib/mailkube/resources/emails.rb', line 12

def initialize(transport)
  @transport = transport
  freeze
end

Instance Method Details

#idempotency(key) ⇒ Hash{String => String}

Build the body as one hash literal and drop the nils in a single pass, rather than a chain of body["x"] = x if x. That keeps this method's cyclomatic complexity at 1 no matter how many optional fields the API grows, and is why an unset field is absent from the wire rather than sent as null.

Parameters:

  • key (String, nil) —

    the caller's idempotency key.

  • (String, nil)

Returns:

  • (Hash{String => String}) —

    the per-request headers.



78
 
# File 'lib/mailkube/resources/emails.rb', line 78

def idempotency(key) = key.nil? ? {} : { "Idempotency-Key" => key }

#send(from:, to:, subject:, html: nil, text: nil, cc: nil, bcc: nil, reply_to: nil, headers: nil, attachments: nil, tags: nil, template_id: nil, template_version: nil, variables: nil, topic: nil, idempotency_key: nil, scheduled_at: nil, batch_id: nil) ⇒ Email

Send an email.

Supply html and/or text for a raw send, or template_id for a saved template. idempotency_key travels as the Idempotency-Key header rather than in the body. Passing scheduled_at schedules the send instead of delivering it now; the result then reports Email#scheduled?.

This method shadows Object#send on this object only, which is deliberate: every mailkube SDK spells the verb emails.send, and a Ruby-only name would break that. Use __send__ if you need reflective dispatch on a resource.

Parameters:

  • from (String) —

    the sender address, optionally with a display name.

  • to (String, Array<String>) —

    the recipient address or addresses.

  • subject (String) —

    the subject line.

  • html (String, nil) (defaults to: nil) —

    the HTML body, for a raw-content send.

  • text (String, nil) (defaults to: nil) —

    the plain-text body, for a raw-content send.

  • cc (Array<String>, nil) (defaults to: nil) —

    carbon-copy recipients.

  • bcc (Array<String>, nil) (defaults to: nil) —

    blind carbon-copy recipients.

  • reply_to (String, Array<String>, nil) (defaults to: nil) —

    the Reply-To addresses.

  • headers (Hash{String => String}, nil) (defaults to: nil) —

    custom message headers.

  • attachments (Array<Attachment>, nil) (defaults to: nil) —

    the file attachments.

  • tags (Array<Tag>, nil) (defaults to: nil) —

    free-form name/value tags forwarded to the server.

  • template_id (String, nil) (defaults to: nil) —

    the UUID of a saved template to render.

  • template_version (String, nil) (defaults to: nil) —

    a template version number, or "latest".

  • variables (Hash, nil) (defaults to: nil) —

    values for the template's placeholders.

  • topic (String, nil) (defaults to: nil) —

    the mailing-list topic slug this send is attributed to.

  • idempotency_key (String, nil) (defaults to: nil) —

    sent as the Idempotency-Key header.

  • scheduled_at (Time, String, nil) (defaults to: nil) —

    schedules the send instead of sending now.

  • batch_id (String, nil) (defaults to: nil) —

    groups several scheduled sends.

Returns:

  • (Email) —

    the accepted-send result.

Raises:



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/mailkube/resources/emails.rb', line 49

def send(from:, to:, subject:, html: nil, text: nil, cc: nil, bcc: nil, reply_to: nil, headers: nil,
         attachments: nil, tags: nil, template_id: nil, template_version: nil, variables: nil,
         topic: nil, idempotency_key: nil, scheduled_at: nil, batch_id: nil)
  # One hash literal, then a single `compact`, rather than a chain of `body["x"] = x if x`.
  # That keeps this method's cyclomatic complexity at 1 no matter how many optional fields
  # the API grows, and is why an unset field is absent from the wire rather than null.
  body = {
    "from" => from, "to" => to, "subject" => subject,
    "html" => html, "text" => text, "cc" => cc, "bcc" => bcc,
    "reply_to" => reply_to, "headers" => headers,
    "attachments" => Serialization.encode_attachments(attachments),
    "tags" => Serialization.encode_tags(tags),
    "template_id" => template_id, "template_version" => template_version,
    "variables" => variables, "topic" => topic,
    "scheduled_at" => Serialization.to_iso(scheduled_at), "batch_id" => batch_id
  }.compact

  @transport.send_email(RequestSpec.new(path: "emails", body: body, headers: idempotency(idempotency_key)))
end