Class: NeverBounce::API::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/never_bounce/api/client.rb

Overview

API client.

client = NeverBounce::API::Client.new(api_key: "api_key")

response = client.
# => #<NeverBounce::API::Response::AccountInfo> or
# => #<NeverBounce::API::ErrorMessage>

response = client.single_check(credits_info: true, email: "[email protected]", timeout: 3)
# => #<NeverBounce::API::Response::JobsDownload> or
# => #<NeverBounce::API::ErrorMessage>

response = client.jobs_search(page: 1, per_page: 10)
# => #<NeverBounce::API::Response::JobsSearch> or
# => #<NeverBounce::API::ErrorMessage>

# ...

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#api_key ⇒ String

API key.

Returns:

  • (String) 


44
45
46
 
# File 'lib/never_bounce/api/client.rb', line 44

def api_key
  @api_key or raise AttributeError, "Attribute must be set: api_key"
end

Instance Method Details

#account_info ⇒ Response::AccountInfo, Response::ErrorMessage

Make an account/info request.

Returns:

Raises:

See Also:



67
68
69
70
71
 
# File 'lib/never_bounce/api/client.rb', line 67

def 
  response_to(Request::AccountInfo.new({
    api_key: api_key,
  }))
end

#jobs_create(auto_parse: false, auto_start: false, filename: nil, remote_input: nil, run_sample: false, supplied_input: nil) ⇒ Response::JobsCreate, Response::ErrorMessage

Make a jobs/create request.

Parameters:

  • auto_parse (Boolean) (defaults to: false)
  • auto_start (Boolean) (defaults to: false)
  • filename (Boolean) (defaults to: nil) —

    Default is "YYYYMMDD-HHMMSS.csv" based on current time.

  • remote_input (String) (defaults to: nil) —

    E.g. "http://isp.com/emails.csv".

  • run_sample (Boolean) (defaults to: false)
  • supplied_input (Array<Array<email, name>>) (defaults to: nil) —

    E.g. [["[email protected]", "Alice Roberts"], ["[email protected]", "Bob Smith"]].

Returns:

Raises:

See Also:



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/never_bounce/api/client.rb', line 86

def jobs_create(auto_parse: false, auto_start: false, filename: nil, remote_input: nil, run_sample: false, supplied_input: nil)
  raise ArgumentError, "`remote_input` and `supplied_input` can't both be given" if remote_input && supplied_input

  input_location = if (v = remote_input)
    # NOTE: Logical order: type, then value.
    input = v
    "remote_url"
  elsif (v = supplied_input)
    input = v
    "supplied"
  else
    # NOTE: Not exactly sure what to raise here. From procedure standpoint missing argument is an `ArgumentError`.
    raise ArgumentError, "Input not given, use `remote_input` or `supplied_input`"
  end

  filename ||= Time.now.strftime("%Y%m%d-%H%M%S.csv")

  response_to(API::Request::JobsCreate.new({
    api_key: api_key,
    auto_parse: auto_parse,
    auto_start: auto_start,
    filename: filename,
    input: input,
    input_location: input_location,
    run_sample: run_sample,
  }))
end

#jobs_delete(job_id: nil) ⇒ Response::JobsDelete, Response::ErrorMessage

Make a jobs/delete request.

Parameters:

  • job_id (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



122
123
124
125
126
127
 
# File 'lib/never_bounce/api/client.rb', line 122

def jobs_delete(job_id: nil)
  response_to(Request::JobsDelete.new({
    api_key: api_key,
    job_id: job_id,
  }))
end

#jobs_download(job_id: nil) ⇒ Response::JobsDownload, Response::ErrorMessage

Make a jobs/download request.

Parameters:

  • job_id (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



137
138
139
140
141
142
 
# File 'lib/never_bounce/api/client.rb', line 137

def jobs_download(job_id: nil)
  response_to(Request::JobsDownload.new({
    api_key: api_key,
    job_id: job_id,
  }))
end

#jobs_parse(auto_start: nil, job_id: nil) ⇒ Response::JobsParse, Response::ErrorMessage

Make a jobs/parse request.

Parameters:

  • auto_start (Boolean) (defaults to: nil)
  • job_id (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



153
154
155
156
157
158
159
 
# File 'lib/never_bounce/api/client.rb', line 153

def jobs_parse(auto_start: nil, job_id: nil)
  response_to(Request::JobsParse.new({
    api_key: api_key,
    auto_start: auto_start,
    job_id: job_id,
  }))
end

#jobs_results(job_id: nil, page: 1, per_page: nil) ⇒ Response::JobsResults, Response::ErrorMessage

Make a jobs/results request.

Parameters:

  • job_id (Integer) (defaults to: nil)
  • page (Integer) (defaults to: 1)
  • per_page (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



171
172
173
174
175
176
177
178
 
# File 'lib/never_bounce/api/client.rb', line 171

def jobs_results(job_id: nil, page: 1, per_page: nil)
  response_to(Request::JobsResults.new({
    api_key: api_key,
    job_id: job_id,
    page: page,
    per_page: per_page,
  }))
end

#jobs_search(job_id: nil, page: 1, per_page: nil) ⇒ Response::JobsSearch, Response::ErrorMessage

Make a jobs/search request.

Parameters:

  • job_id (Integer) (defaults to: nil)
  • page (Integer) (defaults to: 1)
  • per_page (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



190
191
192
193
194
195
196
197
 
# File 'lib/never_bounce/api/client.rb', line 190

def jobs_search(job_id: nil, page: 1, per_page: nil)
  response_to(Request::JobsSearch.new({
    api_key: api_key,
    job_id: job_id,
    page: page,
    per_page: per_page,
  }))
end

#jobs_start(job_id: nil, run_sample: nil) ⇒ Response::JobsResults, Response::ErrorMessage

Make a jobs/start request.

Parameters:

  • job_id (Integer) (defaults to: nil)
  • run_sample (Boolean) (defaults to: nil)

Returns:

Raises:

See Also:



208
209
210
211
212
213
214
 
# File 'lib/never_bounce/api/client.rb', line 208

def jobs_start(job_id: nil, run_sample: nil)
  response_to(Request::JobsStart.new({
    api_key: api_key,
    job_id: job_id,
    run_sample: run_sample,
  }))
end

#jobs_status(job_id: nil) ⇒ Response::JobsStatus, Response::ErrorMessage

Make a jobs/status request.

Parameters:

  • job_id (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



224
225
226
227
228
229
 
# File 'lib/never_bounce/api/client.rb', line 224

def jobs_status(job_id: nil)
  response_to(Request::JobsStatus.new({
    api_key: api_key,
    job_id: job_id,
  }))
end

#poe_confirm(email: nil, transaction_id: nil, confirmation_token: nil, result: nil) ⇒ Response::POEConfirm, Response::ErrorMessage

Make a poe/confirm request.

Parameters:

  • email (String) (defaults to: nil)
  • transaction_id (String) (defaults to: nil)
  • confirmation_token (String) (defaults to: nil)
  • result (String) (defaults to: nil)

Returns:

Raises:

See Also:



263
264
265
266
267
268
269
270
271
 
# File 'lib/never_bounce/api/client.rb', line 263

def poe_confirm(email: nil, transaction_id: nil, confirmation_token: nil, result: nil)
  response_to(Request::POEConfirm.new({
    api_key: api_key,
    email: email,
    transaction_id: transaction_id,
    confirmation_token: confirmation_token,
    result: result,
  }))
end

#response_to(request) ⇒ Object (private)

Wrap request in a session, return response.

Parameters:

Returns:



53
54
55
 
# File 'lib/never_bounce/api/client.rb', line 53

def response_to(request)
  Session.new(request: request).response
end

#single_check(address_info: nil, credits_info: nil, email: nil, timeout: nil) ⇒ Response::SingleCheck, Response::ErrorMessage

Make a single/check request.

Parameters:

  • address_info (Boolean) (defaults to: nil)
  • credits_info (Boolean) (defaults to: nil)
  • email (String) (defaults to: nil)
  • timeout (Integer) (defaults to: nil)

Returns:

Raises:

See Also:



242
243
244
245
246
247
248
249
250
 
# File 'lib/never_bounce/api/client.rb', line 242

def single_check(address_info: nil, credits_info: nil, email: nil, timeout: nil)
  response_to(Request::SingleCheck.new({
    address_info: address_info,
    api_key: api_key,
    credits_info: credits_info,
    email: email,
    timeout: timeout,
  }))
end