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

#api_version ⇒ String

API version.

Returns:

  • (String) 


50
51
52
 
# File 'lib/never_bounce/api/client.rb', line 50

def api_version
  @api_version
end

Instance Method Details

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

Make an account/info request.

Returns:

Raises:

See Also:



73
74
75
76
77
78
 
# File 'lib/never_bounce/api/client.rb', line 73

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

#jobs_create(auto_parse: false, auto_start: false, filename: nil, remote_input: nil, run_sample: false, supplied_input: nil, historical: 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:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/never_bounce/api/client.rb', line 93

def jobs_create(auto_parse: false, auto_start: false, filename: nil, remote_input: nil, run_sample: false, supplied_input: nil, historical: 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,
    api_version: api_version,
    auto_parse: auto_parse,
    auto_start: auto_start,
    filename: filename,
    input: input,
    input_location: input_location,
    run_sample: run_sample,
    historical: historical,
  }))
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:



131
132
133
134
135
136
137
 
# File 'lib/never_bounce/api/client.rb', line 131

def jobs_delete(job_id: nil)
  response_to(Request::JobsDelete.new({
    api_key: api_key,
    api_version: api_version,
    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:



147
148
149
150
151
152
153
 
# File 'lib/never_bounce/api/client.rb', line 147

def jobs_download(job_id: nil)
  response_to(Request::JobsDownload.new({
    api_key: api_key,
    api_version: api_version,
    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:



164
165
166
167
168
169
170
171
 
# File 'lib/never_bounce/api/client.rb', line 164

def jobs_parse(auto_start: nil, job_id: nil)
  response_to(Request::JobsParse.new({
    api_key: api_key,
    api_version: api_version,
    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:



183
184
185
186
187
188
189
190
191
 
# File 'lib/never_bounce/api/client.rb', line 183

def jobs_results(job_id: nil, page: 1, per_page: nil)
  response_to(Request::JobsResults.new({
    api_key: api_key,
    api_version: api_version,
    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:



203
204
205
206
207
208
209
210
211
 
# File 'lib/never_bounce/api/client.rb', line 203

def jobs_search(job_id: nil, page: 1, per_page: nil)
  response_to(Request::JobsSearch.new({
    api_key: api_key,
    api_version: api_version,
    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:



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

def jobs_start(job_id: nil, run_sample: nil)
  response_to(Request::JobsStart.new({
    api_key: api_key,
    api_version: api_version,
    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:



239
240
241
242
243
244
245
 
# File 'lib/never_bounce/api/client.rb', line 239

def jobs_status(job_id: nil)
  response_to(Request::JobsStatus.new({
    api_key: api_key,
    api_version: api_version,
    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:



281
282
283
284
285
286
287
288
289
290
 
# File 'lib/never_bounce/api/client.rb', line 281

def poe_confirm(email: nil, transaction_id: nil, confirmation_token: nil, result: nil)
  response_to(Request::POEConfirm.new({
    api_key: api_key,
    api_version: api_version,
    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:



59
60
61
 
# File 'lib/never_bounce/api/client.rb', line 59

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

#single_check(address_info: nil, credits_info: nil, email: nil, timeout: nil, historical: 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:



258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/never_bounce/api/client.rb', line 258

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