zerobounce-sdk 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +184 -17
- data/README.md +26 -13
- data/lib/zerobounce/api_key.rb +238 -7
- data/lib/zerobounce/api_urls.rb +53 -0
- data/lib/zerobounce/base_request.rb +199 -82
- data/lib/zerobounce/client.rb +12 -4
- data/lib/zerobounce/configuration.rb +19 -3
- data/lib/zerobounce/error.rb +19 -7
- data/lib/zerobounce/get_file_helper.rb +40 -27
- data/lib/zerobounce/http_transport.rb +229 -0
- data/lib/zerobounce/priority3.rb +187 -46
- data/lib/zerobounce/request.rb +25 -42
- data/lib/zerobounce/response_error.rb +27 -4
- data/lib/zerobounce/response_shape.rb +190 -0
- data/lib/zerobounce/strict_bool.rb +23 -0
- data/lib/zerobounce/strict_json.rb +165 -0
- data/lib/zerobounce/version.rb +1 -1
- data/lib/zerobounce/warmup.rb +155 -69
- data/lib/zerobounce.rb +138 -97
- metadata +5 -15
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'net/http'
|
|
4
|
+
require 'uri'
|
|
5
|
+
require 'cgi'
|
|
6
|
+
require 'openssl'
|
|
7
|
+
require 'securerandom'
|
|
8
|
+
require 'stringio'
|
|
9
|
+
require 'zlib'
|
|
10
|
+
require 'zerobounce/error'
|
|
11
|
+
|
|
12
|
+
# rubocop:disable Metrics/ModuleLength, Metrics/ParameterLists, Metrics/AbcSize, Metrics/MethodLength
|
|
13
|
+
# rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
|
|
14
|
+
module Zerobounce
|
|
15
|
+
# The SDK's HTTP layer, on Ruby's built-in Net::HTTP (no runtime dependency).
|
|
16
|
+
#
|
|
17
|
+
# One request, one response: no redirects are followed, nothing is logged
|
|
18
|
+
# (Net::HTTP's debug output is never switched on), and every transport
|
|
19
|
+
# failure (refused, reset, timeout, TLS, a body cut short) raises
|
|
20
|
+
# {ApiResponseError} with status 0 and a redacted message. An HTTP error
|
|
21
|
+
# status is NOT raised here: the response comes back and the caller turns it
|
|
22
|
+
# into an error.
|
|
23
|
+
module HttpTransport
|
|
24
|
+
OPEN_TIMEOUT = 30
|
|
25
|
+
READ_TIMEOUT = 120
|
|
26
|
+
WRITE_TIMEOUT = 120
|
|
27
|
+
|
|
28
|
+
# Response headers, readable as headers[:content_type] or
|
|
29
|
+
# headers['Content-Type'] (any case).
|
|
30
|
+
class Headers < Hash
|
|
31
|
+
def self.normalize(key)
|
|
32
|
+
key.to_s.downcase.tr('-', '_').to_sym
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
def [](key)
|
|
36
|
+
super(self.class.normalize(key))
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def key?(key)
|
|
40
|
+
super(self.class.normalize(key))
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# The parts of a response the SDK reads: #code (Integer), #body (String),
|
|
45
|
+
# #headers.
|
|
46
|
+
class Response
|
|
47
|
+
attr_reader :code, :body, :headers
|
|
48
|
+
|
|
49
|
+
def initialize(code, body, headers)
|
|
50
|
+
@code = code
|
|
51
|
+
@body = body
|
|
52
|
+
@headers = headers
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
def to_s
|
|
56
|
+
@body
|
|
57
|
+
end
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
module_function
|
|
61
|
+
|
|
62
|
+
# @param redact [#call] turns an error text into its redacted form
|
|
63
|
+
def execute(method:, url:, query: nil, headers: {}, body: nil, redact: nil)
|
|
64
|
+
redact ||= ->(text) { text }
|
|
65
|
+
uri = build_uri(url, query)
|
|
66
|
+
request = build_request(method, uri, headers, body)
|
|
67
|
+
perform(uri, request, redact)
|
|
68
|
+
rescue ApiResponseError
|
|
69
|
+
raise
|
|
70
|
+
rescue StandardError => e
|
|
71
|
+
raise failure(e, redact), cause: nil
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
def failure(error, redact)
|
|
75
|
+
ApiResponseError.new(
|
|
76
|
+
redact.call("The request to ZeroBounce failed (#{error.class}): #{error.message}"), 0
|
|
77
|
+
)
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
def build_uri(url, query)
|
|
81
|
+
encoded = encode_query(query)
|
|
82
|
+
full = url.to_s
|
|
83
|
+
full += (full.include?('?') ? '&' : '?') + encoded unless encoded.empty?
|
|
84
|
+
URI.parse(full)
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
def build_request(method, uri, headers, body)
|
|
88
|
+
klass = Net::HTTP.const_get(method.to_s.capitalize)
|
|
89
|
+
request = klass.new(uri.request_uri)
|
|
90
|
+
# Identity: Net::HTTP would otherwise ask for gzip, decompress it and
|
|
91
|
+
# drop Content-Length, so a body cut short could no longer be told from a
|
|
92
|
+
# complete one.
|
|
93
|
+
request['Accept-Encoding'] = 'identity'
|
|
94
|
+
request['Accept'] = '*/*'
|
|
95
|
+
headers.each { |name, value| request[name.to_s.tr('_', '-')] = value.to_s unless value.nil? }
|
|
96
|
+
request.body = body unless body.nil?
|
|
97
|
+
request
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
def perform(uri, request, redact)
|
|
101
|
+
http = Net::HTTP.new(uri.host, uri.port)
|
|
102
|
+
http.use_ssl = uri.scheme == 'https'
|
|
103
|
+
http.open_timeout = OPEN_TIMEOUT
|
|
104
|
+
http.read_timeout = READ_TIMEOUT
|
|
105
|
+
http.write_timeout = WRITE_TIMEOUT
|
|
106
|
+
# No silent second send: Net::HTTP would otherwise re-send an idempotent
|
|
107
|
+
# request (GET, PUT, DELETE) once after an EOF or reset, and a validation
|
|
108
|
+
# GET is billable.
|
|
109
|
+
http.max_retries = 0
|
|
110
|
+
http.start do
|
|
111
|
+
http.request(request) { |res| return wrap(res, redact) }
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
def wrap(res, redact)
|
|
116
|
+
headers = Headers.new
|
|
117
|
+
res.each_header { |name, value| headers[Headers.normalize(name)] = value }
|
|
118
|
+
raw = res.read_body.to_s.b
|
|
119
|
+
check_length!(res, raw, redact)
|
|
120
|
+
body = decode(res, raw, redact)
|
|
121
|
+
Response.new(res.code.to_i, with_charset(body, res['content-type']), headers)
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# Fewer bytes than Content-Length is a failure, status 0 (a connection
|
|
125
|
+
# that closes mid-body must not read as a complete response). A list-form
|
|
126
|
+
# header ("50, 50") counts as its value when every entry agrees; entries
|
|
127
|
+
# that differ are a failure too.
|
|
128
|
+
def check_length!(res, raw, redact)
|
|
129
|
+
return if [204, 304].include?(res.code.to_i)
|
|
130
|
+
|
|
131
|
+
lengths = res['content-length'].to_s.split(',').map(&:strip)
|
|
132
|
+
return if lengths.empty? || lengths.any? { |length| !length.match?(/\A\d+\z/) }
|
|
133
|
+
|
|
134
|
+
if lengths.uniq.size > 1
|
|
135
|
+
raise ApiResponseError.new(
|
|
136
|
+
redact.call("The response from ZeroBounce had conflicting Content-Length values (#{lengths.join(', ')})."), 0
|
|
137
|
+
)
|
|
138
|
+
end
|
|
139
|
+
return unless raw.bytesize < lengths.first.to_i
|
|
140
|
+
|
|
141
|
+
raise ApiResponseError.new(
|
|
142
|
+
redact.call("The response from ZeroBounce was cut short: #{raw.bytesize} of #{lengths.first} " \
|
|
143
|
+
'bytes arrived before the connection closed.'), 0
|
|
144
|
+
)
|
|
145
|
+
end
|
|
146
|
+
|
|
147
|
+
# Identity is requested, so a compressed body is unexpected; if a server
|
|
148
|
+
# sends one anyway it must be a complete stream (a gzip body without its
|
|
149
|
+
# trailer is a body cut short).
|
|
150
|
+
def decode(res, raw, redact)
|
|
151
|
+
case res['content-encoding'].to_s.downcase
|
|
152
|
+
when 'gzip', 'x-gzip'
|
|
153
|
+
gunzip(raw)
|
|
154
|
+
when 'deflate'
|
|
155
|
+
Zlib::Inflate.inflate(raw)
|
|
156
|
+
else
|
|
157
|
+
raw
|
|
158
|
+
end
|
|
159
|
+
rescue Zlib::Error
|
|
160
|
+
# cause: nil, so the Zlib error (whose message can quote the raw body)
|
|
161
|
+
# is not carried along.
|
|
162
|
+
raise ApiResponseError.new(redact.call('The response from ZeroBounce could not be decoded.'), 0), cause: nil
|
|
163
|
+
end
|
|
164
|
+
|
|
165
|
+
def gunzip(raw)
|
|
166
|
+
reader = Zlib::GzipReader.new(StringIO.new(raw))
|
|
167
|
+
text = reader.read.to_s
|
|
168
|
+
reader.finish # raises Zlib::GzipFile::Error unless the stream (with its trailer) was complete
|
|
169
|
+
text
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
def with_charset(body, content_type)
|
|
173
|
+
charset = content_type.to_s[/charset=["']?([\w.:-]+)/i, 1]
|
|
174
|
+
encoding = begin
|
|
175
|
+
charset ? Encoding.find(charset) : Encoding::UTF_8
|
|
176
|
+
rescue ArgumentError
|
|
177
|
+
Encoding::UTF_8
|
|
178
|
+
end
|
|
179
|
+
body.dup.force_encoding(encoding)
|
|
180
|
+
end
|
|
181
|
+
|
|
182
|
+
# key=value pairs, nested hashes as k[sub] and arrays as k[].
|
|
183
|
+
def flatten_params(params, parent = nil)
|
|
184
|
+
return [] if params.nil?
|
|
185
|
+
|
|
186
|
+
params.flat_map do |key, value|
|
|
187
|
+
name = parent ? "#{parent}[#{key}]" : key.to_s
|
|
188
|
+
if value.is_a?(Hash)
|
|
189
|
+
flatten_params(value, name)
|
|
190
|
+
elsif value.is_a?(Array)
|
|
191
|
+
value.flat_map { |item| item.is_a?(Hash) ? flatten_params(item, "#{name}[]") : [["#{name}[]", item]] }
|
|
192
|
+
else
|
|
193
|
+
[[name, value]]
|
|
194
|
+
end
|
|
195
|
+
end
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
def encode_query(params)
|
|
199
|
+
flatten_params(params).map do |key, value|
|
|
200
|
+
value.nil? ? CGI.escape(key) : "#{CGI.escape(key)}=#{CGI.escape(value.to_s)}"
|
|
201
|
+
end.join('&')
|
|
202
|
+
end
|
|
203
|
+
|
|
204
|
+
# A multipart/form-data body, built here. Returns [content_type, body].
|
|
205
|
+
# +file+ is { name:, filename:, content:, content_type: }.
|
|
206
|
+
def multipart(fields, file)
|
|
207
|
+
boundary = "----ZerobounceRubyBoundary#{SecureRandom.hex(16)}"
|
|
208
|
+
body = String.new(encoding: Encoding::BINARY)
|
|
209
|
+
flatten_params(fields).each do |name, value|
|
|
210
|
+
body << "--#{boundary}\r\n".b
|
|
211
|
+
body << "Content-Disposition: form-data; name=\"#{quote(name)}\"\r\n\r\n".b
|
|
212
|
+
body << value.to_s.b << "\r\n".b
|
|
213
|
+
end
|
|
214
|
+
body << "--#{boundary}\r\n".b
|
|
215
|
+
body << "Content-Disposition: form-data; name=\"#{quote(file[:name])}\"; " \
|
|
216
|
+
"filename=\"#{quote(file[:filename])}\"\r\n".b
|
|
217
|
+
body << "Content-Type: #{file[:content_type]}\r\n\r\n".b
|
|
218
|
+
body << file[:content].to_s.b << "\r\n--#{boundary}--\r\n".b
|
|
219
|
+
["multipart/form-data; boundary=#{boundary}", body]
|
|
220
|
+
end
|
|
221
|
+
|
|
222
|
+
# A header parameter value: raw UTF-8, a quote as %22, CR and LF removed.
|
|
223
|
+
def quote(text)
|
|
224
|
+
text.to_s.delete("\r\n").gsub('"', '%22')
|
|
225
|
+
end
|
|
226
|
+
end
|
|
227
|
+
end
|
|
228
|
+
# rubocop:enable Metrics/ModuleLength, Metrics/ParameterLists, Metrics/AbcSize, Metrics/MethodLength
|
|
229
|
+
# rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
|
data/lib/zerobounce/priority3.rb
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require 'date'
|
|
3
4
|
require 'erb'
|
|
5
|
+
require 'uri'
|
|
6
|
+
require 'zerobounce/strict_bool'
|
|
7
|
+
require 'zerobounce/response_shape'
|
|
4
8
|
|
|
5
9
|
module Zerobounce
|
|
6
10
|
module Priority3
|
|
@@ -13,65 +17,85 @@ module Zerobounce
|
|
|
13
17
|
INBOX_PLACEMENT_PAGE_SIZE_MIN = 1
|
|
14
18
|
INBOX_PLACEMENT_PAGE_SIZE_MAX = 100
|
|
15
19
|
|
|
20
|
+
INBOX_PLACEMENT_STATUSES = %w[running finished].freeze
|
|
21
|
+
IPT_CREATE_OPTIONS = %i[test_type sender_email provider_ids seed_ids providers webhook_url].freeze
|
|
22
|
+
IPT_LIST_OPTIONS = %i[status created_after created_before page page_size].freeze
|
|
23
|
+
FILE_JOB_OPTIONS = %i[return_url remove_duplicates].freeze
|
|
24
|
+
# The custom filters' documented values (as the Python SDK checks them).
|
|
25
|
+
FILTER_RULES = %w[allow block].freeze
|
|
26
|
+
FILTER_TARGETS = %w[email domain mx tld].freeze
|
|
27
|
+
|
|
16
28
|
def zb_request
|
|
17
29
|
Zerobounce.class_variable_get(:@@request)
|
|
18
30
|
end
|
|
19
31
|
|
|
20
32
|
def send_email_finder_file(filepath, domain_column:, first_name_column: nil, last_name_column: nil,
|
|
21
33
|
middle_name_column: nil, full_name_column: nil, has_header_row: nil)
|
|
22
|
-
|
|
34
|
+
params = { domain_column: __column__(domain_column, 'domain_column') }
|
|
35
|
+
{
|
|
36
|
+
first_name_column: first_name_column, last_name_column: last_name_column,
|
|
37
|
+
middle_name_column: middle_name_column, full_name_column: full_name_column
|
|
38
|
+
}.each do |name, value|
|
|
39
|
+
# A blank name column is "not given", so the one-of check below speaks.
|
|
40
|
+
next if value.nil? || (value.is_a?(String) && value.strip.empty?)
|
|
41
|
+
|
|
42
|
+
params[name] = __column__(value, name.to_s)
|
|
43
|
+
end
|
|
23
44
|
# One of the two name columns tells the finder what to look for; with
|
|
24
45
|
# neither there is nothing to build a local part from.
|
|
25
|
-
if
|
|
46
|
+
if params[:first_name_column].nil? && params[:full_name_column].nil?
|
|
26
47
|
raise ArgumentError, 'first_name_column or full_name_column is required'
|
|
27
48
|
end
|
|
28
49
|
|
|
29
|
-
params = { domain_column: domain_column }
|
|
30
50
|
params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
|
|
31
|
-
params[:first_name_column] = first_name_column unless first_name_column.nil?
|
|
32
|
-
params[:last_name_column] = last_name_column unless last_name_column.nil?
|
|
33
|
-
params[:middle_name_column] = middle_name_column unless middle_name_column.nil?
|
|
34
|
-
params[:full_name_column] = full_name_column unless full_name_column.nil?
|
|
35
51
|
zb_request.bulk_root_post("#{EMAIL_FINDER_BULK_BASE}/sendfile", params, 'multipart/form-data', filepath)
|
|
36
52
|
end
|
|
37
53
|
|
|
38
54
|
def email_finder_file_status(file_id)
|
|
55
|
+
__require_text__(file_id, 'file_id')
|
|
39
56
|
zb_request.bulk_root_get("#{EMAIL_FINDER_BULK_BASE}/filestatus", { file_id: file_id })
|
|
40
57
|
end
|
|
41
58
|
|
|
42
59
|
def email_finder_file_get(file_id)
|
|
60
|
+
__require_text__(file_id, 'file_id')
|
|
43
61
|
zb_request.bulk_root_getfile("#{EMAIL_FINDER_BULK_BASE}/getfile", { file_id: file_id })
|
|
44
62
|
end
|
|
45
63
|
|
|
46
64
|
def email_finder_file_delete(file_id)
|
|
65
|
+
__require_text__(file_id, 'file_id')
|
|
47
66
|
zb_request.bulk_root_get("#{EMAIL_FINDER_BULK_BASE}/deletefile", { file_id: file_id })
|
|
48
67
|
end
|
|
49
68
|
|
|
50
69
|
def send_domain_search_file(filepath, domain_column:, has_header_row: nil)
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
params = { domain_column: domain_column }
|
|
70
|
+
params = { domain_column: __column__(domain_column, 'domain_column') }
|
|
54
71
|
params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
|
|
55
72
|
zb_request.bulk_root_post("#{DOMAIN_SEARCH_BULK_BASE}/sendfile", params, 'multipart/form-data', filepath)
|
|
56
73
|
end
|
|
57
74
|
|
|
58
75
|
def domain_search_file_status(file_id)
|
|
76
|
+
__require_text__(file_id, 'file_id')
|
|
59
77
|
zb_request.bulk_root_get("#{DOMAIN_SEARCH_BULK_BASE}/filestatus", { file_id: file_id })
|
|
60
78
|
end
|
|
61
79
|
|
|
62
80
|
def domain_search_file_get(file_id)
|
|
81
|
+
__require_text__(file_id, 'file_id')
|
|
63
82
|
zb_request.bulk_root_getfile("#{DOMAIN_SEARCH_BULK_BASE}/getfile", { file_id: file_id })
|
|
64
83
|
end
|
|
65
84
|
|
|
66
85
|
def domain_search_file_delete(file_id)
|
|
86
|
+
__require_text__(file_id, 'file_id')
|
|
67
87
|
zb_request.bulk_root_get("#{DOMAIN_SEARCH_BULK_BASE}/deletefile", { file_id: file_id })
|
|
68
88
|
end
|
|
69
89
|
|
|
70
90
|
def send_list_evaluator_file(filepath, email_address_column:)
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
91
|
+
params = { email_address_column: __column__(email_address_column, 'email_address_column') }
|
|
92
|
+
# The same base URL as get_list_evaluator_result, not the bulk one. The
|
|
93
|
+
# endpoint is the base URL itself, with its trailing slash.
|
|
94
|
+
ResponseShape.check!(
|
|
95
|
+
zb_request.bulk_post('', params, 'multipart/form-data', filepath,
|
|
96
|
+
root: Zerobounce.configuration.list_evaluator_root_url),
|
|
97
|
+
:list_evaluator
|
|
98
|
+
)
|
|
75
99
|
end
|
|
76
100
|
|
|
77
101
|
def get_list_evaluator_result(file_id)
|
|
@@ -79,11 +103,14 @@ module Zerobounce
|
|
|
79
103
|
|
|
80
104
|
# The list evaluator has its own base URL, not a path built from the bulk
|
|
81
105
|
# one, and the file id is one path segment, so a slash must stay encoded.
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
106
|
+
ResponseShape.check!(
|
|
107
|
+
zb_request.root_request(
|
|
108
|
+
:get,
|
|
109
|
+
Zerobounce.configuration.list_evaluator_root_url,
|
|
110
|
+
"#{ERB::Util.url_encode(file_id.to_s.strip)}/",
|
|
111
|
+
{}
|
|
112
|
+
),
|
|
113
|
+
:list_evaluator
|
|
87
114
|
)
|
|
88
115
|
end
|
|
89
116
|
|
|
@@ -102,11 +129,12 @@ module Zerobounce
|
|
|
102
129
|
end
|
|
103
130
|
|
|
104
131
|
def add_filter(rule:, target:, value:)
|
|
132
|
+
__check_filter__(rule, target, value)
|
|
105
133
|
zb_request.post('filters/add', { rule: rule, target: target, value: value }, 'application/x-www-form-urlencoded')
|
|
106
134
|
end
|
|
107
135
|
|
|
108
136
|
def list_filters(use_post: false)
|
|
109
|
-
if use_post
|
|
137
|
+
if __strict_bool__(use_post, 'use_post')
|
|
110
138
|
zb_request.post('filters/list', {}, 'application/x-www-form-urlencoded')
|
|
111
139
|
else
|
|
112
140
|
zb_request.get('filters/list', {})
|
|
@@ -114,13 +142,16 @@ module Zerobounce
|
|
|
114
142
|
end
|
|
115
143
|
|
|
116
144
|
def delete_filter(rule:, target:, value:)
|
|
145
|
+
__check_filter__(rule, target, value)
|
|
117
146
|
zb_request.post('filters/delete', { rule: rule, target: target, value: value }, 'application/x-www-form-urlencoded')
|
|
118
147
|
end
|
|
119
148
|
|
|
120
149
|
def list_s3_files(bucket: nil, search: nil)
|
|
121
150
|
params = {}
|
|
122
|
-
|
|
123
|
-
|
|
151
|
+
bucket = __omit_blank__(bucket, 'bucket')
|
|
152
|
+
search = __omit_blank__(search, 'search')
|
|
153
|
+
params[:bucket] = bucket unless bucket.nil?
|
|
154
|
+
params[:search] = search unless search.nil?
|
|
124
155
|
# The S3 listing lives on the bulkapi ROOT, like the jobs below it, not
|
|
125
156
|
# under /v2 - bulk_get would send it to /v2/listS3files, which is a 404.
|
|
126
157
|
zb_request.bulk_root_get('listS3files', params)
|
|
@@ -139,12 +170,13 @@ module Zerobounce
|
|
|
139
170
|
# export_bucket is optional: omit it and the export goes to the bucket in
|
|
140
171
|
# your ZeroBounce settings, the way export_sftp_file's export_path does.
|
|
141
172
|
def export_s3_file(file_id:, export_bucket: nil)
|
|
142
|
-
|
|
143
|
-
|
|
173
|
+
__require_text__(file_id, 'file_id')
|
|
144
174
|
if !export_bucket.nil? && export_bucket.to_s.strip.empty?
|
|
145
175
|
raise ArgumentError, 'export_bucket is required'
|
|
146
176
|
end
|
|
147
177
|
|
|
178
|
+
__require_text__(export_bucket, 'export_bucket') unless export_bucket.nil?
|
|
179
|
+
|
|
148
180
|
params = { file_id: file_id }
|
|
149
181
|
params[:export_bucket] = export_bucket unless export_bucket.nil?
|
|
150
182
|
zb_request.bulk_root_form_post('exportS3file', params)
|
|
@@ -187,12 +219,13 @@ module Zerobounce
|
|
|
187
219
|
# Note the field name: this endpoint takes export_path, not the
|
|
188
220
|
# export_bucket that export_s3_file sends. Omit it to use your settings.
|
|
189
221
|
def export_sftp_file(file_id:, export_path: nil)
|
|
190
|
-
|
|
191
|
-
|
|
222
|
+
__require_text__(file_id, 'file_id')
|
|
192
223
|
if !export_path.nil? && export_path.to_s.strip.empty?
|
|
193
224
|
raise ArgumentError, 'export_path is required'
|
|
194
225
|
end
|
|
195
226
|
|
|
227
|
+
__require_text__(export_path, 'export_path') unless export_path.nil?
|
|
228
|
+
|
|
196
229
|
params = { file_id: file_id }
|
|
197
230
|
params[:export_path] = export_path unless export_path.nil?
|
|
198
231
|
zb_request.bulk_root_form_post('exportSFTPfile', params)
|
|
@@ -216,7 +249,10 @@ module Zerobounce
|
|
|
216
249
|
# three are rejected by the API, so they are caught before a request that
|
|
217
250
|
# would spend inbox-test credits.
|
|
218
251
|
def create_inbox_placement_test(name, **options)
|
|
252
|
+
__check_options__(options, IPT_CREATE_OPTIONS)
|
|
219
253
|
raise ArgumentError, 'name is required' if name.nil? || name.to_s.strip.empty?
|
|
254
|
+
|
|
255
|
+
__require_text__(name, 'name')
|
|
220
256
|
raise ArgumentError, 'name must be 64 characters or fewer' if name.to_s.strip.length > INBOX_PLACEMENT_NAME_MAX
|
|
221
257
|
|
|
222
258
|
if options.key?(:test_type)
|
|
@@ -225,6 +261,13 @@ module Zerobounce
|
|
|
225
261
|
raise ArgumentError, 'sender_email is required when test_type is 1'
|
|
226
262
|
end
|
|
227
263
|
end
|
|
264
|
+
__require_text__(options[:sender_email], 'sender_email') if options.key?(:sender_email)
|
|
265
|
+
__https_url__(options[:webhook_url], 'webhook_url') if options.key?(:webhook_url)
|
|
266
|
+
%i[provider_ids seed_ids providers].each do |key|
|
|
267
|
+
next unless options.key?(key)
|
|
268
|
+
|
|
269
|
+
raise ArgumentError, "Invalid parameter: #{key} must be an array" unless options[key].is_a?(Array)
|
|
270
|
+
end
|
|
228
271
|
|
|
229
272
|
body = { 'name' => name }
|
|
230
273
|
{
|
|
@@ -235,6 +278,7 @@ module Zerobounce
|
|
|
235
278
|
providers: 'providers',
|
|
236
279
|
webhook_url: 'webhookUrl'
|
|
237
280
|
}.each { |key, wire| body[wire] = options[key] if options.key?(key) }
|
|
281
|
+
body['testType'] = test_type if options.key?(:test_type)
|
|
238
282
|
|
|
239
283
|
zb_request.ipt_request(:post, 'test', {}, json: body)
|
|
240
284
|
end
|
|
@@ -244,14 +288,28 @@ module Zerobounce
|
|
|
244
288
|
end
|
|
245
289
|
|
|
246
290
|
def list_inbox_placement_tests(**options)
|
|
291
|
+
__check_options__(options, IPT_LIST_OPTIONS)
|
|
247
292
|
params = {}
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
293
|
+
if options.key?(:status)
|
|
294
|
+
status = options[:status]
|
|
295
|
+
raise ArgumentError, 'status must be running or finished' unless INBOX_PLACEMENT_STATUSES.include?(status)
|
|
296
|
+
|
|
297
|
+
params[:status] = status
|
|
298
|
+
end
|
|
299
|
+
{ created_after: :createdAfter, created_before: :createdBefore }.each do |key, wire|
|
|
300
|
+
params[wire] = __iso_date__(options[key], key.to_s) if options.key?(key)
|
|
301
|
+
end
|
|
302
|
+
if options.key?(:page)
|
|
303
|
+
page = options[:page]
|
|
304
|
+
raise ArgumentError, 'Invalid parameter: page must be an integer' unless page.is_a?(Integer)
|
|
305
|
+
raise ArgumentError, 'Invalid parameter: page (must be 1 or more)' if page < 1
|
|
306
|
+
|
|
307
|
+
params[:page] = page
|
|
308
|
+
end
|
|
252
309
|
if options.key?(:page_size)
|
|
253
310
|
page_size = options[:page_size]
|
|
254
|
-
unless
|
|
311
|
+
unless page_size.is_a?(Integer) &&
|
|
312
|
+
(INBOX_PLACEMENT_PAGE_SIZE_MIN..INBOX_PLACEMENT_PAGE_SIZE_MAX).cover?(page_size)
|
|
255
313
|
raise ArgumentError,
|
|
256
314
|
"page_size must be between #{INBOX_PLACEMENT_PAGE_SIZE_MIN} and #{INBOX_PLACEMENT_PAGE_SIZE_MAX}"
|
|
257
315
|
end
|
|
@@ -276,6 +334,7 @@ module Zerobounce
|
|
|
276
334
|
def set_inbox_placement_webhook(webhook_url)
|
|
277
335
|
raise ArgumentError, 'webhook_url is required' if webhook_url.nil? || webhook_url.to_s.strip.empty?
|
|
278
336
|
|
|
337
|
+
__https_url__(webhook_url, 'webhook_url')
|
|
279
338
|
zb_request.ipt_request(:put, 'webhook', {}, json: { 'webhookUrl' => webhook_url })
|
|
280
339
|
end
|
|
281
340
|
|
|
@@ -287,19 +346,45 @@ module Zerobounce
|
|
|
287
346
|
value.nil? || value.to_s.strip.empty?
|
|
288
347
|
end
|
|
289
348
|
|
|
290
|
-
# A
|
|
291
|
-
#
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
349
|
+
# A required text argument: a String with something in it, else an
|
|
350
|
+
# ArgumentError before anything is sent.
|
|
351
|
+
def __require_text__(value, name)
|
|
352
|
+
raise ArgumentError, "Empty parameter: #{name}" if value.nil? || (value.is_a?(String) && value.strip.empty?)
|
|
353
|
+
raise ArgumentError, "Invalid parameter: #{name} must be a string" unless value.is_a?(String)
|
|
354
|
+
|
|
355
|
+
value
|
|
356
|
+
end
|
|
357
|
+
|
|
358
|
+
# An optional text argument that is simply left out (nil) when it is nil
|
|
359
|
+
# or blank, and must be a String otherwise.
|
|
360
|
+
def __omit_blank__(value, name)
|
|
361
|
+
return nil if value.nil? || (value.is_a?(String) && value.strip.empty?)
|
|
362
|
+
|
|
363
|
+
__require_text__(value, name)
|
|
364
|
+
end
|
|
296
365
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
366
|
+
# A whole-number option in low..high seconds (nil is left to the caller).
|
|
367
|
+
def __whole_seconds__(value, name, low, high)
|
|
368
|
+
unless value.is_a?(Integer)
|
|
369
|
+
raise ArgumentError, "Invalid parameter: #{name} must be a whole number of seconds"
|
|
301
370
|
end
|
|
302
|
-
|
|
371
|
+
return value if value >= low && value <= high
|
|
372
|
+
|
|
373
|
+
raise ArgumentError, "Invalid parameter: #{name} (must be between #{low} and #{high} seconds)"
|
|
374
|
+
end
|
|
375
|
+
|
|
376
|
+
# A column index: an Integer (not a boolean or a String) of 1 or more.
|
|
377
|
+
def __column__(value, name)
|
|
378
|
+
raise ArgumentError, "Empty parameter: #{name}" if value.nil?
|
|
379
|
+
raise ArgumentError, "Invalid parameter: #{name} must be an integer" unless value.is_a?(Integer)
|
|
380
|
+
raise ArgumentError, "Invalid parameter: #{name} (must be 1 or more)" if value < 1
|
|
381
|
+
|
|
382
|
+
value
|
|
383
|
+
end
|
|
384
|
+
|
|
385
|
+
# A boolean option, parsed strictly (see StrictBool).
|
|
386
|
+
def __strict_bool__(value, name)
|
|
387
|
+
StrictBool.parse(value, name)
|
|
303
388
|
end
|
|
304
389
|
|
|
305
390
|
# A strict boolean option as the string the API expects on the wire.
|
|
@@ -307,13 +392,14 @@ module Zerobounce
|
|
|
307
392
|
__strict_bool__(value, name) ? 'true' : 'false'
|
|
308
393
|
end
|
|
309
394
|
|
|
395
|
+
# An Integer, or a String of digits only ("2"), as callers have passed it; "2x" is refused.
|
|
310
396
|
def __inbox_placement_test_type__(value)
|
|
311
|
-
|
|
312
|
-
unless INBOX_PLACEMENT_TEST_TYPES.include?(
|
|
397
|
+
value = value.to_i if value.is_a?(String) && value.match?(/\A\d+\z/)
|
|
398
|
+
unless value.is_a?(Integer) && INBOX_PLACEMENT_TEST_TYPES.include?(value)
|
|
313
399
|
raise ArgumentError, "test_type must be one of #{INBOX_PLACEMENT_TEST_TYPES.join(', ')}"
|
|
314
400
|
end
|
|
315
401
|
|
|
316
|
-
|
|
402
|
+
value
|
|
317
403
|
end
|
|
318
404
|
|
|
319
405
|
# POSTs one of the eight documented S3 / SFTP file jobs on the bulkapi root.
|
|
@@ -325,10 +411,12 @@ module Zerobounce
|
|
|
325
411
|
# docs list both as optional. Without either the API answers "This field is
|
|
326
412
|
# required".
|
|
327
413
|
def bulk_root_file_job(path, file_name, has_header_row, **options)
|
|
414
|
+
__check_options__(options, FILE_JOB_OPTIONS)
|
|
328
415
|
raise ArgumentError, 'file_name is required' if __blank__(file_name)
|
|
329
416
|
raise ArgumentError, 'return_url is required' if __blank__(options[:return_url])
|
|
330
417
|
|
|
331
|
-
|
|
418
|
+
__require_text__(file_name, 'file_name')
|
|
419
|
+
return_url = __http_url__(options[:return_url], 'return_url')
|
|
332
420
|
|
|
333
421
|
params = {
|
|
334
422
|
has_header_row: __wire_bool__(has_header_row, 'has_header_row'),
|
|
@@ -342,6 +430,59 @@ module Zerobounce
|
|
|
342
430
|
zb_request.bulk_root_form_post(path, params)
|
|
343
431
|
end
|
|
344
432
|
|
|
433
|
+
# Unknown option keys are a typo, never silently dropped.
|
|
434
|
+
def __check_options__(options, known)
|
|
435
|
+
unknown = options.keys - known
|
|
436
|
+
return if unknown.empty?
|
|
437
|
+
|
|
438
|
+
raise ArgumentError, "Unknown option#{'s' if unknown.length > 1}: #{unknown.join(', ')} " \
|
|
439
|
+
"(known: #{known.join(', ')})"
|
|
440
|
+
end
|
|
441
|
+
|
|
442
|
+
def __check_filter__(rule, target, value)
|
|
443
|
+
if [rule, target, value].any? { |item| !item.is_a?(String) || item.strip.empty? }
|
|
444
|
+
raise ArgumentError, 'Empty parameter: rule, target, and value are required'
|
|
445
|
+
end
|
|
446
|
+
raise ArgumentError, 'Invalid parameter: rule (must be allow or block)' unless FILTER_RULES.include?(rule)
|
|
447
|
+
return if FILTER_TARGETS.include?(target)
|
|
448
|
+
|
|
449
|
+
raise ArgumentError, 'Invalid parameter: target (must be email, domain, mx or tld)'
|
|
450
|
+
end
|
|
451
|
+
|
|
452
|
+
# An http(s) URL with a host, as a String.
|
|
453
|
+
def __http_url__(value, name, schemes = %w[http https])
|
|
454
|
+
__require_text__(value, name)
|
|
455
|
+
uri = begin
|
|
456
|
+
URI.parse(value.strip)
|
|
457
|
+
rescue URI::InvalidURIError
|
|
458
|
+
nil
|
|
459
|
+
end
|
|
460
|
+
unless uri && schemes.include?(uri.scheme.to_s.downcase) && !uri.host.to_s.empty?
|
|
461
|
+
raise ArgumentError, "Invalid parameter: #{name} must be #{schemes.map { |x| "#{x}://" }.join(' or ')} URL"
|
|
462
|
+
end
|
|
463
|
+
|
|
464
|
+
value
|
|
465
|
+
end
|
|
466
|
+
|
|
467
|
+
def __https_url__(value, name)
|
|
468
|
+
__http_url__(value, name, %w[https])
|
|
469
|
+
end
|
|
470
|
+
|
|
471
|
+
# A strict YYYY-MM-DD date (or a Date/Time), as a string for the wire.
|
|
472
|
+
def __iso_date__(value, name)
|
|
473
|
+
return value.strftime('%Y-%m-%d') if value.is_a?(Date) || value.is_a?(Time)
|
|
474
|
+
|
|
475
|
+
if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
|
|
476
|
+
begin
|
|
477
|
+
Date.strptime(value, '%Y-%m-%d')
|
|
478
|
+
return value
|
|
479
|
+
rescue ArgumentError
|
|
480
|
+
nil
|
|
481
|
+
end
|
|
482
|
+
end
|
|
483
|
+
raise ArgumentError, "Invalid parameter: #{name} must be a YYYY-MM-DD date"
|
|
484
|
+
end
|
|
485
|
+
|
|
345
486
|
def inbox_placement_test_segment(test_id)
|
|
346
487
|
raise ArgumentError, 'test_id is required' if test_id.nil? || test_id.to_s.strip.empty?
|
|
347
488
|
|