mailganer-client 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50c26307907b4bef90ebe1b4daa6ffd346d0f6004388bda060ec6a2e3a13d723
+  data.tar.gz: 5b0d78aebd7f2d8e4b4b01822de2152535cbf777b9142dba3188192642ca5ff7
+SHA512:
+  metadata.gz: 8bf65344a758e33f61c58b91af7c91e2ce678be97504c07fe4151e8c5484376971b5a5966811d04603df18590359049718f14eb2e23945ced487e230ac48e5b1
+  data.tar.gz: 72ea6ddee8baefc7979edd9cf576bcb9d1a49052ec082ce4d0a68d3a646d3503eee377888f086415ff3a8b4ff45190e2b8302487967099038e4d704dd54bc752

data/README.md

@@ -0,0 +1,122 @@
+# Mailganer Client
+
+A simple Ruby client for the Mailganer API.\
+Designed to make sending requests and integrating with the service
+effortless.
+
+## 🚀 Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem "mailganer-client"
+```
+
+Then install:
+
+``` bash
+bundle install
+```
+
+Or install it manually:
+
+``` bash
+gem install mailganer-client
+```
+
+## 📦 Usage
+
+``` ruby
+require "mailganer_client"
+
+MailganerClient.configure do |config|
+  config.api_key: "your-smtp-api-key",
+  config.smtp_login: "xxx",
+  config.api_key_web_portal: "your-web-portal-api-key"
+end
+
+client = MailganerClient.new
+
+response = client.send_email(
+  to: "user@example.com",
+  from: "info@mysite.com",
+  subject: "Hello!",
+  body: "Your message goes here"
+)
+
+puts response
+```
+
+``` ruby
+
+response = client.get_fbl_report_by_date(date_from: "2020-01-01", date_to: "2026-01-01")
+
+puts response
+```
+
+
+``` ruby
+
+response = client.send_email_smtp_v1(
+    type: 'template',
+    to: "test@test.com",
+    subject: "subject",
+    template_id: "template_id from mailganer web portal",
+    params:  {
+      name: 'Test name',
+      unsubscribeUrl: ''
+    },
+    from: "from@mysite.com",
+    name_from: "Sender name from@mysite.com"
+  )
+
+puts response
+```
+
+
+``` ruby
+
+#file_path = Rails.root.join('app', 'javascript', 'src', 'public', 'img', 'test-image.jpg')
+#file_path = File.expand_path("test-image.jpg", __dir__)
+require 'base64'
+
+response = client.send_email_smtp_v1(
+    type: 'template',
+    to: "test@test.com",
+    subject: "subject",
+    template_id: "template_id from mailganer web portal",
+    params:  {
+      name: 'Test name'
+    },
+    from: "from@mysite.com",
+    body: "Hello, {{name}}",  
+    name_from: "Sender name from@mysite.com",
+    attach_files: [
+        {
+          name: File.basename("file_path"),
+          filebody: Base64.strict_encode64(File.read("file_path"))
+        }
+      ]
+    )
+
+puts response
+```
+
+## ⚙️ Configuration
+
+``` ruby
+MailganerClient.configure do |config|
+  config.api_key: "your-smtp-api-key",
+  config.smtp_login: "xxx",
+  config.api_key_web_portal: "your-web-portal-api-key"
+end
+```
+
+```
+
+## 🏗 Development
+
+``` bash
+git clone https://github.com/yetisamurai/mailganer_client.git
+cd mailganer_client
+```

data/lib/mailganer_client.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+require "net/http"
+require "uri"
+require "json"
+
+##
+# Client for interacting with the Mailganer API.
+#
+# Provides sending emails, bulk mailing, stop-list operations,
+# statistics, domain management, and delivery status checks.
+#
+# @example Sending a simple email
+#   client = MailganerClient.new(
+#     api_key: "...",
+#     smtp_login: "...",
+#     api_key_web_portal: "..."
+#   )
+#   client.send_email(
+#     to: "user@example.com",
+#     subject: "Hello",
+#     body: "Email body",
+#     from: "sender@example.com"
+#  
+class MailganerClient
+  class ApiError < StandardError
+    attr_reader :code, :body
+  end
+  class StopListError < ApiError; end
+  class DomainNotTrustedError < ApiError; end
+  class AuthorizationError < ApiError; end
+  class BadRequestError < ApiError; end
+
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  class Configuration
+    attr_accessor :api_key, :smtp_login, :api_key_web_portal, :host, :debug
+  end
+
+  ##
+  # Initializes API client
+  #
+  # @param api_key [String]  SMTP API key for sending
+  # @param smtp_login [String] SMTP login 
+  # @param api_key_web_portal [String] API key for web portal
+  # @param debug [Boolean] enable HTTP debug logging
+  # @param host [String] base API URL
+  #
+
+  def 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
+    )
+    @api_key = api_key
+    @api_key_web_portal = api_key_web_portal
+    @host = host.chomp('/') + '/'
+    @smtp_login = smtp_login
+    @debug = debug
+  end
+
+  private
+
+  ##
+  # Executes a HTTP request
+  #
+  # @param method [String] HTTP method (GET/POST)
+  # @param endpoint [String] API endpoint
+  # @param data [Hash,nil] request body
+  # @param without_content_type [Boolean] remove Content-Type header
+  #
+  # @return [Hash] parsed JSON response
+  # @raise [ApiError] if API returns an error
+  #
+
+  def request(method, endpoint, data = nil, without_content_type = false)
+    uri = URI.join(@host, endpoint)
+
+    if (method.upcase == 'GET' && data)
+      uri.query = URI.encode_www_form(data)
+    end
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.read_timeout = 10
+
+    req = case method.upcase
+          when 'GET' then Net::HTTP::Get.new(uri)
+          when 'POST' then Net::HTTP::Post.new(uri)
+          else raise ApiError, "Unsupported method #{method}"
+          end
+
+    if !without_content_type
+      req['Content-Type'] = 'application/json'
+    end
+    req['Authorization'] = @api_key
+    req['Mg-Api-Key'] = @api_key_web_portal
+
+    req.body = data.to_json if data
+
+    if (@debug)
+      puts "==== HTTP DEBUG ===="
+      puts "Method: #{method.upcase}"
+      puts "URL: #{uri}"
+      puts "Headers: #{req.each_header.to_h}"
+      puts "Body: #{req.body}" if req.body
+      puts "==================="
+    end
+
+    begin
+      res = http.request(req)
+    rescue Timeout::Error
+      raise ApiError, 'Request timed out'
+    rescue SocketError => e
+      raise ApiError, e&.message
+    end
+
+    json = JSON.parse(res.body, symbolize_names: true)
+
+    unless res.code.to_i == 200 && json[:status].to_s.downcase == "ok"
+      message = json[:message] || "API error"
+
+      if message.include?("550 bounced check filter")
+        raise StopListError, message
+      elsif message.include?("from domain not trusted")
+        raise DomainNotTrustedError, message
+      elsif res.code.to_i == 403
+        raise AuthorizationError, message
+      elsif res.code.to_i == 400
+        raise BadRequestError, message
+      else
+        raise ApiError, message
+      end
+    end
+
+    json
+  end
+
+  ##
+  # Validates email format
+  #
+  # @param email [String]
+  # @raise [ApiError] if invalid
+  #
+
+  def validate_email!(email)
+    raise ApiError, 'Invalid email' unless email =~ URI::MailTo::EMAIL_REGEXP
+  end
+
+  public
+
+  ##
+  # Sends a simple email
+  #
+  # @param to [String] recipient email
+  # @param subject [String] subject line
+  # @param body [String,nil] message body
+  # @param from [String] sender email
+  # @param name_from [String,nil] sender name
+  # @param params [Hash,nil] template params
+  #
+  # @return [Hash]
+  #
+
+  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
+
+  ##
+  # Sends email using SMTP v1 (template or raw body)
+  #
+  # @param type [String] "template" or "body"
+  # @param to [String]
+  # @param subject [String]
+  # @param body [String,nil]
+  # @param from [String]
+  # @param name_from [String,nil]
+  # @param template_id [Integer,nil]
+  # @param params [Hash,nil]
+  # @param attach_files [Array]
+  #
+  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
+
+  ##
+  # Sends a bulk email package
+  #
+  # @param users [Array<Hash>] recipient data
+  # @param subject [String]
+  # @param body [String]
+  # @param from [String]
+  # @param name_from [String,nil]
+  #
+  def send_emails_package(users:, subject:, body:, from:, name_from: nil)
+    validate_email!(from)
+
+    # "users": [
+    #   {
+    #     "emailto": "to1@domain.com", // Имейл получателя
+    # "name": "Вася", // любые переменные
+    # "field1": "400",
+    #   "products": [
+    #   {
+    #     "name":"foo1",
+    #     "price":"bar1",
+    #     "link":"baz1"
+    #   },
+    #   {
+    #     "name":"foo2",
+    #     "price":"bar2",
+    #     "link":"baz2"
+    #   }
+    # ] // пример вложенного массива
+    #     },
+    #     {
+    #         "emailto": "to2@domain.com",
+    #         "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
+
+  ##
+  # Stops a bulk email package
+  #
+  # @param pack_id [Integer]
+  #
+  def stop_emails_package(pack_id:)
+    params = { key: @api_key, pack_id: pack_id }
+    request('GET', "api/v1/package_stop", params)
+  end
+
+
+  ##
+  # Gets status of a bulk package
+  #
+  # @param pack_id [Integer]
+  #
+  def status_emails_package(pack_id:)
+    params = { issuen: pack_id}
+    request('GET', "api/v2/package/status", params)
+  end
+
+  ##
+  # Gets delivery status of a specific message
+  #
+  # @param email [String,nil]
+  # @param x_track_id [String,nil]
+  # @param message_id [String,nil]
+  #
+  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
+
+  ##
+  # Retrieves statistics
+  #
+  # @param date_from [String]
+  # @param date_to [String]
+  # @param limit [Integer]
+  # @param cursor_next [String,nil]
+  # @param timestamp_from [Integer,nil]
+  # @param timestamp_to [Integer,nil]
+  #
+  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
+
+
+  ##
+  # Non-delivered emails by date
+  #
+  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
+
+  ##
+  # Non-delivered emails by issue
+  #
+  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
+
+  ##
+  # FBL (abuse complaints) by date
+  #
+  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
+
+  ##
+  # FBL (abuse complaints) by issue
+  #
+  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
+
+  ##
+  # Searches email in stop-list
+  #
+  # @param email [String]
+  #
+  def stop_list_search(email:)
+    validate_email!(email)
+    request('GET', 'api/v2/stop-list/search', { email: email })
+  end
+
+  ##
+  # Adds email to stop-list
+  #
+  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
+
+  ##
+  # Removes email from stop-list
+  #
+  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
+
+
+  ##
+  # Checks domain verification status
+  #
+  def domain_check_verification(domain:,client_name:)
+    request('POST',"api/v2/blist/domains/verify", {domain: domain, client: client_name})
+  end
+
+  ##
+  # Adds domain
+  #
+  def domains_add(domain:)
+    params = { domain: domain }
+    request('POST',"api/v2/blist/domains/add", params)
+  end
+
+  ##
+  # Removes domain
+  #
+  def domains_remove(domain:)
+    params = { domain: domain }
+    request('POST', "api/v2/blist/domains/remove", params)
+  end
+
+  ##
+  # Lists all domains
+  #
+  # @return [Hash]
+  #
+  def domains_list
+    request('GET', "api/v2/blist/domains")
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: mailganer-client
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- yetisamurai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Full Ruby wrapper for Mailganer email API, FBL, stop-list, statistics.
+email:
+- yetisamurai@proton.me
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/mailganer_client.rb
+homepage: https://github.com/yetisamurai/mailganer_client
+licenses:
+- CC0-1.0
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Ruby client for Mailganer API
+test_files: []