Class: Mailfloss::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/mailfloss/client.rb,
sig/mailfloss.rbs

Overview

Entry point for the mailfloss API.

client = Mailfloss::Client.new(api_key: "mf_rk_...")
client.verify(email: "jane@acme.com")

The API key falls back to ENV when the kwarg is omitted. All requests are retried automatically on 429 / 5xx (honoring Retry-After) and on transient connection errors.

Constant Summary collapse

DEFAULT_BASE_URL =

Returns:

  • (String) 
"https://api.mailfloss.com/v1"
DEFAULT_MAX_RETRIES =

Returns:

  • (Integer) 
3
DEFAULT_TIMEOUT =

Returns:

  • (Integer) 
30
RETRY_BASE_DELAY =

Returns:

  • (Float) 
0.5
RETRY_MAX_DELAY =

Returns:

  • (Float) 
8.0
USER_AGENT =

Returns:

  • (String) 
"mailfloss-ruby/#{VERSION}"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: DEFAULT_BASE_URL, max_retries: DEFAULT_MAX_RETRIES, timeout: DEFAULT_TIMEOUT, transport: nil, sleeper: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

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

    falls back to ENV

  • base_url (String) (defaults to: DEFAULT_BASE_URL)
  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    retries after the initial attempt

  • timeout (Numeric) (defaults to: DEFAULT_TIMEOUT) —

    per-request open/read timeout in seconds

  • transport (#call, nil) (defaults to: nil) —

    injectable transport: call(method, url, headers, body) -> #status/#headers/#body

  • sleeper (#call, nil) (defaults to: nil) —

    injectable sleep proc (tests pass ->(_s){})



33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/mailfloss/client.rb', line 33

def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, max_retries: DEFAULT_MAX_RETRIES,
               timeout: DEFAULT_TIMEOUT, transport: nil, sleeper: nil)
  @api_key = api_key || ENV["MAILFLOSS_API_KEY"]
  if @api_key.nil? || @api_key.to_s.strip.empty?
    raise ConfigurationError,
          "No API key. Pass api_key: to Mailfloss::Client.new or set the " \
          "MAILFLOSS_API_KEY environment variable."
  end
  @base_url = base_url.sub(%r{/+\z}, "")
  @max_retries = max_retries
  @timeout = timeout
  @transport = transport || Transport.new(timeout: timeout)
  @sleeper = sleeper || ->(seconds) { sleep(seconds) }
end

Instance Attribute Details

#base_url ⇒ String (readonly)

Returns the value of attribute base_url.

Returns:

  • (String) 


24
25
26
 
# File 'lib/mailfloss/client.rb', line 24

def base_url
  @base_url
end

#max_retries ⇒ Integer (readonly)

Returns the value of attribute max_retries.

Returns:

  • (Integer) 


24
25
26
 
# File 'lib/mailfloss/client.rb', line 24

def max_retries
  @max_retries
end

#timeout ⇒ Numeric (readonly)

Returns the value of attribute timeout.

Returns:

  • (Numeric) 


24
25
26
 
# File 'lib/mailfloss/client.rb', line 24

def timeout
  @timeout
end

Instance Method Details

#account ⇒ Resources::Account

Returns:



86
87
88
 
# File 'lib/mailfloss/client.rb', line 86

def 
  @account ||= Resources::Account.new(self)
end

#batch_verify ⇒ Resources::BatchVerify

Returns:



70
71
72
 
# File 'lib/mailfloss/client.rb', line 70

def batch_verify
  @batch_verify ||= Resources::BatchVerify.new(self)
end

#check_key(api_key: nil, public_key: nil, check_plan: nil, get_token: nil, check_credits: nil) ⇒ Object

GET /check-key



63
64
65
66
67
68
 
# File 'lib/mailfloss/client.rb', line 63

def check_key(api_key: nil, public_key: nil, check_plan: nil, get_token: nil, check_credits: nil)
  request(:get, "/check-key", query: {
            api_key: api_key, public_key: public_key, check_plan: check_plan,
            get_token: get_token, check_credits: check_credits
          })
end

#erasures ⇒ Resources::Erasures

Returns:



98
99
100
 
# File 'lib/mailfloss/client.rb', line 98

def erasures
  @erasures ||= Resources::Erasures.new(self)
end

#integrations ⇒ Resources::Integrations

Returns:



94
95
96
 
# File 'lib/mailfloss/client.rb', line 94

def integrations
  @integrations ||= Resources::Integrations.new(self)
end

#jobs ⇒ Resources::Jobs

Returns:



74
75
76
 
# File 'lib/mailfloss/client.rb', line 74

def jobs
  @jobs ||= Resources::Jobs.new(self)
end

#organization ⇒ Resources::Organization

Returns:



90
91
92
 
# File 'lib/mailfloss/client.rb', line 90

def organization
  @organization ||= Resources::Organization.new(self)
end

#reports ⇒ Resources::Reports

Returns:



82
83
84
 
# File 'lib/mailfloss/client.rb', line 82

def reports
  @reports ||= Resources::Reports.new(self)
end

#request(method, path, query: nil, body: nil, idempotency_key: nil) ⇒ Object?

Perform an authenticated request against the API.

Parameters:

  • method (Symbol) —

    :get, :post, :patch, :delete

  • path (String) —

    resource path relative to base_url (e.g. "/verify")

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

    query params; nil values are dropped

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

    JSON-serialized when present

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

    POST only; auto-generated when nil

Returns:

  • (Object, nil) —

    parsed JSON (symbolized keys), or nil on empty body

Raises:



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/mailfloss/client.rb', line 112

def request(method, path, query: nil, body: nil, idempotency_key: nil)
  url = build_url(path, query)
  headers = {
    "Authorization" => "Bearer #{@api_key}",
    "Accept" => "application/json",
    "User-Agent" => USER_AGENT
  }
  headers["Content-Type"] = "application/json" if body
  if method == :post
    headers["Idempotency-Key"] = idempotency_key || SecureRandom.uuid
  end
  payload = body ? JSON.generate(body) : nil

  response = perform_with_retries(method, url, headers, payload)
  status = response_status(response)
  raise APIError.new(status: status, body: response_body(response)) unless (200..299).cover?(status)

  parse_body(response_body(response))
end

#users ⇒ Resources::Users

Returns:



78
79
80
 
# File 'lib/mailfloss/client.rb', line 78

def users
  @users ||= Resources::Users.new(self)
end

#verify(email:, timeout: nil) ⇒ Types::verify_result

GET /verify

Parameters:

  • email: (String)
  • timeout: (Numeric, String, nil) (defaults to: nil)

Returns:

  • (Types::verify_result) 


56
57
58
 
# File 'lib/mailfloss/client.rb', line 56

def verify(email:, timeout: nil)
  request(:get, "/verify", query: { email: email, timeout: timeout })
end