Class: Axene::Mailer::Resources::Emails

Inherits:
Object
  • Object
show all
Defined in:
lib/axene/mailer/resources/emails.rb

Overview

The emails resource: send, look up, search, schedule, and inspect messages. Accessed as client.emails.

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ Emails

Returns a new instance of Emails.

Parameters:



10
11
12
 
# File 'lib/axene/mailer/resources/emails.rb', line 10

def initialize(transport)
  @transport = transport
end

Instance Method Details

#cancel_scheduled(id) ⇒ Hash

Cancel a scheduled email.

Parameters:

  • id (String)

Returns:

  • (Hash) —

    { id:, status: }



105
106
107
 
# File 'lib/axene/mailer/resources/emails.rb', line 105

def cancel_scheduled(id)
  @transport.request(:delete, "/v1/emails/scheduled/#{escape(id)}")
end

#events(id) ⇒ Array<Hash>

List delivery / open / click / bounce events for an email.

Parameters:

  • id (String)

Returns:

  • (Array<Hash>) 


68
69
70
 
# File 'lib/axene/mailer/resources/emails.rb', line 68

def events(id)
  @transport.request(:get, "/v1/emails/#{escape(id)}/events")
end

#get(id) ⇒ Hash

Fetch a single email with its bodies and events.

Parameters:

  • id (String)

Returns:

  • (Hash) 


60
61
62
 
# File 'lib/axene/mailer/resources/emails.rb', line 60

def get(id)
  @transport.request(:get, "/v1/emails/#{escape(id)}")
end

#get_saved_searches ⇒ Array<Hash>

Get the caller’s saved searches.

Returns:

  • (Array<Hash>) 


130
131
132
 
# File 'lib/axene/mailer/resources/emails.rb', line 130

def get_saved_searches
  @transport.request(:get, "/v1/emails/saved-searches")[:searches]
end

#list(status: nil, page: 0, limit: 20) ⇒ Array<Hash>

List recent emails, newest first.

Parameters:

  • status (String, nil) (defaults to: nil)
  • page (Integer) (defaults to: 0) —

    zero-based, default 0

  • limit (Integer) (defaults to: 20) —

    default 20

Returns:

  • (Array<Hash>) 


52
53
54
 
# File 'lib/axene/mailer/resources/emails.rb', line 52

def list(status: nil, page: 0, limit: 20)
  @transport.request(:get, "/v1/emails/", query: { status: status, page: page, limit: limit })
end

#list_scheduled ⇒ Array<Hash>

List emails scheduled for future delivery, soonest first.

Returns:

  • (Array<Hash>) 


97
98
99
 
# File 'lib/axene/mailer/resources/emails.rb', line 97

def list_scheduled
  @transport.request(:get, "/v1/emails/scheduled")
end

#retry(id) ⇒ Hash

Re-send a bounced, rejected, or failed email as a new message.

Parameters:

  • id (String)

Returns:

  • (Hash) 


76
77
78
 
# File 'lib/axene/mailer/resources/emails.rb', line 76

def retry(id)
  @transport.request(:post, "/v1/emails/#{escape(id)}/retry")
end

#search(q: nil, status: nil, tag: nil, page: 0, limit: 20) ⇒ Array<Hash>

Search emails. q supports inline tokens (to:, from:, status:, domain:, tag:); leftover words are matched as free text.

Parameters:

  • q (String, nil) (defaults to: nil)
  • status (String, nil) (defaults to: nil)
  • tag (String, nil) (defaults to: nil)
  • page (Integer) (defaults to: 0) —

    zero-based, default 0

  • limit (Integer) (defaults to: 20) —

    default 20

Returns:

  • (Array<Hash>) 


89
90
91
92
 
# File 'lib/axene/mailer/resources/emails.rb', line 89

def search(q: nil, status: nil, tag: nil, page: 0, limit: 20)
  @transport.request(:get, "/v1/emails/search",
                     query: { q: q, status: status, tag: tag, page: page, limit: limit })
end

#send(message = {}, **kwargs) ⇒ Hash

Send a single email.

Accepts keyword arguments or a Hash. The from field is exposed cleanly and mapped to the wire name from_. A bare String is accepted anywhere an address is expected and becomes { email: … }.

Parameters:

  • message (Hash) (defaults to: {}) —

    send parameters (:from, :to, :subject, :html, …)

Returns:

  • (Hash) —

    { id:, status:, message_id:, rejection_reason: }



22
23
24
25
 
# File 'lib/axene/mailer/resources/emails.rb', line 22

def send(message = {}, **kwargs)
  body = serialize_send(message.empty? ? kwargs : message)
  @transport.request(:post, "/v1/emails/", body: body)
end

#send_batch(messages) ⇒ Hash

Send up to your plan’s batch limit in one call. The API accepts a bare array of messages and returns a per-message result set.

Parameters:

  • messages (Array<Hash>)

Returns:

  • (Hash) —

    { total:, sent:, failed:, results: […] }



32
33
34
 
# File 'lib/axene/mailer/resources/emails.rb', line 32

def send_batch(messages)
  @transport.request(:post, "/v1/emails/batch", body: messages.map { |m| serialize_send(m) })
end

#send_scheduled_now(id) ⇒ Hash

Send a scheduled email immediately instead of waiting.

Parameters:

  • id (String)

Returns:

  • (Hash) —

    { id:, status: }



113
114
115
 
# File 'lib/axene/mailer/resources/emails.rb', line 113

def send_scheduled_now(id)
  @transport.request(:post, "/v1/emails/scheduled/#{escape(id)}/send-now")
end

#set_saved_searches(searches) ⇒ Array<Hash>

Replace the caller’s saved searches (max 50).

Parameters:

  • searches (Array<Hash>)

Returns:

  • (Array<Hash>) 


138
139
140
 
# File 'lib/axene/mailer/resources/emails.rb', line 138

def set_saved_searches(searches)
  @transport.request(:put, "/v1/emails/saved-searches", body: { searches: searches })[:searches]
end

#updates(since) ⇒ Array<Hash>

Poll for emails whose status changed at or after since (ISO 8601 string or a Time). Capped at 50 rows.

Parameters:

  • since (String, Time)

Returns:

  • (Array<Hash>) 


122
123
124
125
 
# File 'lib/axene/mailer/resources/emails.rb', line 122

def updates(since)
  iso = since.respond_to?(:iso8601) ? since.iso8601 : since
  @transport.request(:get, "/v1/emails/updates", query: { since: iso })
end

#validate(message = {}, **kwargs) ⇒ Hash

Dry-run a send: check whether message would be accepted without actually sending it. Uses the full send body.

Parameters:

  • message (Hash) (defaults to: {})

Returns:

  • (Hash) —

    { valid:, can_send:, issues:, plan:, usage: }



41
42
43
44
 
# File 'lib/axene/mailer/resources/emails.rb', line 41

def validate(message = {}, **kwargs)
  body = serialize_send(message.empty? ? kwargs : message)
  @transport.request(:post, "/v1/emails/validate", body: body)
end