Class: MailganerClient

Inherits:
Object
  • Object
show all
Defined in:
lib/mailganer_client.rb

Overview

Client for interacting with the Mailganer API.

Provides sending emails, bulk mailing, stop-list operations, statistics, domain management, and delivery status checks.

Examples:

Sending a simple email

client = MailganerClient.new(
  api_key: "...",
  smtp_login: "...",
  api_key_web_portal: "..."
)
client.send_email(
  to: "[email protected]",
  subject: "Hello",
  body: "Email body",
  from: "[email protected]"

Defined Under Namespace

Classes: ApiError, AuthorizationError, BadRequestError, Configuration, DomainNotTrustedError, StopListError

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: MailganerClient.configuration&.api_key, smtp_login: MailganerClient.configuration&.smtp_login, api_key_web_portal: MailganerClient.configuration&.api_key_web_portal, host: MailganerClient.configuration&.host || "https://api.samotpravil.ru/", debug: MailganerClient.configuration&.debug || false) ⇒ MailganerClient

Initializes API client

Parameters:

  • api_key (String) (defaults to: MailganerClient.configuration&.api_key) —

    SMTP API key for sending

  • smtp_login (String) (defaults to: MailganerClient.configuration&.smtp_login) —

    SMTP login

  • api_key_web_portal (String) (defaults to: MailganerClient.configuration&.api_key_web_portal) —

    API key for web portal

  • debug (Boolean) (defaults to: MailganerClient.configuration&.debug || false) —

    enable HTTP debug logging

  • host (String) (defaults to: MailganerClient.configuration&.host || "https://api.samotpravil.ru/") —

    base API URL



57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/mailganer_client.rb', line 57

def initialize(
    api_key: MailganerClient.configuration&.api_key,
    smtp_login: MailganerClient.configuration&.,
    api_key_web_portal: MailganerClient.configuration&.api_key_web_portal,
    host: MailganerClient.configuration&.host || "https://api.samotpravil.ru/",
    debug: MailganerClient.configuration&.debug || false
  )
  @api_key = api_key
  @api_key_web_portal = api_key_web_portal
  @host = host.chomp('/') + '/'
   = 
  @debug = debug
end

Class Attribute Details

.configuration ⇒ Object

Returns the value of attribute configuration.



35
36
37
 
# File 'lib/mailganer_client.rb', line 35

def configuration
  @configuration
end

Class Method Details

.configure {|configuration| ... } ⇒ Object

Yields:



38
39
40
41
 
# File 'lib/mailganer_client.rb', line 38

def self.configure
  self.configuration ||= Configuration.new
  yield(configuration)
end

Instance Method Details

#domain_check_verification(domain:, client_name:) ⇒ Object

Checks domain verification status



413
414
415
 
# File 'lib/mailganer_client.rb', line 413

def domain_check_verification(domain:,client_name:)
  request('POST',"api/v2/blist/domains/verify", {domain: domain, client: client_name})
end

#domains_add(domain:) ⇒ Object

Adds domain



420
421
422
423
 
# File 'lib/mailganer_client.rb', line 420

def domains_add(domain:)
  params = { domain: domain }
  request('POST',"api/v2/blist/domains/add", params)
end

#domains_list ⇒ Hash

Lists all domains

Returns:

  • (Hash) 


438
439
440
 
# File 'lib/mailganer_client.rb', line 438

def domains_list
  request('GET', "api/v2/blist/domains")
end

#domains_remove(domain:) ⇒ Object

Removes domain



428
429
430
431
 
# File 'lib/mailganer_client.rb', line 428

def domains_remove(domain:)
  params = { domain: domain }
  request('POST', "api/v2/blist/domains/remove", params)
end

#get_fbl_report_by_date(date_from:, date_to:, limit: 5, cursor_next: nil) ⇒ Object

FBL (abuse complaints) by date



370
371
372
373
 
# File 'lib/mailganer_client.rb', line 370

def get_fbl_report_by_date(date_from:, date_to:, limit: 5, cursor_next: nil)
  params = { date_from: date_from, date_to: date_to, limit: limit, cursor_next: cursor_next }.compact
  request('GET', "api/v2/blist/report/fbl", params)
end

#get_fbl_report_by_issue(issue:, limit: 5, cursor_next: nil) ⇒ Object

FBL (abuse complaints) by issue



378
379
380
381
 
# File 'lib/mailganer_client.rb', line 378

def get_fbl_report_by_issue(issue:, limit: 5, cursor_next: nil)
  params = { issuen: issue, limit: limit, cursor_next: cursor_next }.compact
  request('GET', "api/v2/issue/report/fbl?", params)
end

#get_non_delivery_by_date(date_from:, date_to:, limit: 5, cursor_next: nil, order: nil) ⇒ Object

Non-delivered emails by date



354
355
356
357
 
# File 'lib/mailganer_client.rb', line 354

def get_non_delivery_by_date(date_from:, date_to:, limit: 5, cursor_next: nil, order: nil)
  params = { date_from: date_from, date_to: date_to, limit: limit, cursor_next: cursor_next, order: order }.compact
  request('GET', "api/v2/blist/report/non-delivery", params)
end

#get_non_delivery_by_issue(issue:, limit: 5, cursor_next: nil, order: nil) ⇒ Object

Non-delivered emails by issue



362
363
364
365
 
# File 'lib/mailganer_client.rb', line 362

def get_non_delivery_by_issue(issue:, limit: 5, cursor_next: nil, order: nil)
  params = { issuen: issue, limit: limit, cursor_next: cursor_next, order: order }.compact
  request('GET', "api/v2/issue/report/non-delivery", params)
end

#get_statistics(date_from:, date_to:, limit: 100, cursor_next: nil, timestamp_from: nil, timestamp_to: nil) ⇒ Object

Retrieves statistics

Parameters:

  • date_from (String)
  • date_to (String)
  • limit (Integer) (defaults to: 100)
  • cursor_next (String, nil) (defaults to: nil)
  • timestamp_from (Integer, nil) (defaults to: nil)
  • timestamp_to (Integer, nil) (defaults to: nil) 


328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/mailganer_client.rb', line 328

def get_statistics(date_from:, date_to:, limit: 100, cursor_next: nil, timestamp_from: nil, timestamp_to: nil)
  #?date_from=2023-11-01&date_to=2023-11-07
  #?timestamp_from=1706795600&timestamp_to=1706831999&
  params = {
    date_from: date_from,
    date_to: date_to,
    limit: limit,
    cursor_next: cursor_next,
  }

  if timestamp_from.present? && timestamp_to.present?
    params[:timestamp_from] = timestamp_from
    params[:timestamp_to] = timestamp_to
  elsif date_from.present? && date_to.present?
    params[:date_from] = date_from
    params[:date_to] = date_to
  end

  params.compact!
  request('GET', "api/v2/issue/statistics", params)
end

#send_email(to:, subject:, body: nil, from:, name_from: nil, params: nil) ⇒ Hash

Sends a simple email

Parameters:

  • to (String) —

    recipient email

  • subject (String) —

    subject line

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

    message body

  • from (String) —

    sender email

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

    sender name

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

    template params

Returns:

  • (Hash) 


174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/mailganer_client.rb', line 174

def send_email(to:, subject:, body: nil, from:, name_from: nil, params: nil)
  validate_email!(to)
  validate_email!(from)

  data = {
    email_to: to,
    subject: subject,
    params: params,
    message_text: body,
    email_from: name_from ? "#{name_from} <#{from}>" : from,
  }
  request('POST', 'api/v2/mail/send', data)
end

#send_email_smtp_v1(type:, to:, subject:, body: nil, from:, name_from: nil, template_id: nil, params: nil, attach_files: []) ⇒ Object

Sends email using SMTP v1 (template or raw body)

Parameters:

  • type (String) —

    “template” or “body”

  • to (String)
  • subject (String)
  • body (String, nil) (defaults to: nil)
  • from (String)
  • name_from (String, nil) (defaults to: nil)
  • template_id (Integer, nil) (defaults to: nil)
  • params (Hash, nil) (defaults to: nil)
  • attach_files (Array) (defaults to: []) 


201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/mailganer_client.rb', line 201

def send_email_smtp_v1(type:, to:, subject:, body: nil, from:, name_from: nil, template_id: nil, params: nil, attach_files: [])
  validate_email!(to)
  validate_email!(from)

  data = {
    email_to: to,
    subject: subject,
    params: params,
    check_local_stop_list: true,
    track_open: true,
    track_click: true,
    email_from: name_from ? "#{name_from} <#{from}>" : from,
    attach_files: attach_files,
    x_track_id: "#{@smtp_login}-#{Time.now.to_i}-#{SecureRandom.hex(6)}",
  }

  case type
  when 'template'
    data[:template_id] = template_id
  when 'body'
    data[:message_text] = body
  else
    raise ApiError, "Unsupported type #{type}; select type = template or type = body"
  end

  request('POST', "api/v1/smtp_send?key=#{@api_key}", data)
end

#send_emails_package(users:, subject:, body:, from:, name_from: nil) ⇒ Object

Sends a bulk email package

Parameters:

  • users (Array<Hash>) —

    recipient data

  • subject (String)
  • body (String)
  • from (String)
  • name_from (String, nil) (defaults to: nil) 


238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/mailganer_client.rb', line 238

def send_emails_package(users:, subject:, body:, from:, name_from: nil)
  validate_email!(from)

  # "users": [
  #   {
  #     "emailto": "[email protected]", // Имейл получателя
  # "name": "Вася", // любые переменные
  # "field1": "400",
  #   "products": [
  #   {
  #     "name":"foo1",
  #     "price":"bar1",
  #     "link":"baz1"
  #   },
  #   {
  #     "name":"foo2",
  #     "price":"bar2",
  #     "link":"baz2"
  #   }
  # ] // пример вложенного массива
  #     },
  #     {
  #         "emailto": "[email protected]",
  #         "string_array": [
  #             {"name": "foo1"},
  #             {"name": "foo2"}
  #         ] // пример массива строк
  # },
  #   {
  #     ...
  #   }
  # ] // массив с получателями

  data = {
    email_from: from,
    name_from: name_from,
    subject: subject,
    check_local_stop_list: true,
    track_open: true,
    track_click: true,
    message_text: body,
    users: users
  }

  request('POST', "api/v1/add_json_package?key=#{@api_key}", data)
end

#status_email_delivery(email: nil, x_track_id: nil, message_id: nil) ⇒ Object

Gets delivery status of a specific message

Parameters:

  • email (String, nil) (defaults to: nil)
  • x_track_id (String, nil) (defaults to: nil)
  • message_id (String, nil) (defaults to: nil) 


313
314
315
316
 
# File 'lib/mailganer_client.rb', line 313

def status_email_delivery(email: nil, x_track_id: nil, message_id: nil)
  params = { email: email, x_track_id: x_track_id, message_id: message_id }.compact
  request('GET', "api/v2/issue/status", params)
end

#status_emails_package(pack_id:) ⇒ Object

Gets status of a bulk package

Parameters:

  • pack_id (Integer) 


301
302
303
304
 
# File 'lib/mailganer_client.rb', line 301

def status_emails_package(pack_id:)
  params = { issuen: pack_id}
  request('GET', "api/v2/package/status", params)
end

#stop_emails_package(pack_id:) ⇒ Object

Stops a bulk email package

Parameters:

  • pack_id (Integer) 


290
291
292
293
 
# File 'lib/mailganer_client.rb', line 290

def stop_emails_package(pack_id:)
  params = { key: @api_key, pack_id: pack_id }
  request('GET', "api/v1/package_stop", params)
end

#stop_list_add(email:, mail_from:) ⇒ Object

Adds email to stop-list



396
397
398
399
 
# File 'lib/mailganer_client.rb', line 396

def stop_list_add(email:, mail_from:)
  validate_email!(email)
  request('POST', "api/v2/stop-list/add?#{URI.encode_www_form(mail_from: mail_from, email: email)}", nil, true)
end

#stop_list_remove(email:, mail_from:) ⇒ Object

Removes email from stop-list



404
405
406
407
 
# File 'lib/mailganer_client.rb', line 404

def stop_list_remove(email:, mail_from:)
  validate_email!(email)
  request('POST', "api/v2/stop-list/remove?#{URI.encode_www_form(mail_from: mail_from, email: email)}", nil, true)
end

#stop_list_search(email:) ⇒ Object

Searches email in stop-list

Parameters:

  • email (String) 


388
389
390
391
 
# File 'lib/mailganer_client.rb', line 388

def stop_list_search(email:)
  validate_email!(email)
  request('GET', 'api/v2/stop-list/search', { email: email })
end