mailsentry 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4410aa49c2518ebc3b27ead59b2db6c5f49416f4ddfc16f27bd619c3528d8d7c
+  data.tar.gz: 28712ba826de1c82911569b3d77ef2b09fe30c6c5b74e61a91232ff4da55b098
+SHA512:
+  metadata.gz: d75098031f33199fd14c7ee489217b0fea9c16fb86c9fb0e0b4ad6691dc03a7c84312e37c0c24865b93c0fe1fd594a512be9aef3cc75c370ce9a3cbfd6a860e1
+  data.tar.gz: f7c70e5fff2060a91229a881254cd37328372f061045f7f6ca9b4d45241cfd8480eb0557612eb23ef08ab9bf477bf9755df03462067d9fa35bfde5f1bac0c039

data/README.md

@@ -0,0 +1,151 @@
+# MailSentry Ruby SDK
+
+Official Ruby SDK for the [MailSentry](https://mailsentry.dev) email-validation API.
+
+Validate emails in real time with 8 layers of checks — syntax, MX records, disposable detection, role-based detection, typo suggestions, SMTP verification, gibberish scoring, and spam-trap detection.
+
+## Requirements
+
+- Ruby 3.0+
+- No external dependencies (uses `net/http` and `json` from the standard library)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "mailsentry"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+Or install directly:
+
+```
+gem install mailsentry
+```
+
+## Quick Start
+
+```ruby
+require "mailsentry"
+
+client = MailSentry::Client.new(api_key: "ms_live_your_key_here")
+
+# Validate a single email
+result = client.verify("user@example.com")
+
+puts result["verdict"]  # => "valid", "caution", "risky", or "invalid"
+puts result["score"]    # => 0-100
+puts result["checks"]["disposable"]["is_disposable"]
+```
+
+## Usage
+
+### Initialize the client
+
+```ruby
+client = MailSentry::Client.new(
+  api_key:  "ms_live_your_key_here",
+  base_url: "https://mailsentry.dev",  # optional, default shown
+  timeout:  30                          # optional, seconds
+)
+```
+
+### Single email validation
+
+```ruby
+result = client.verify("user@example.com")
+
+# result is a Hash with these keys:
+# "email", "score", "verdict", "recommendation", "verification_level",
+# "warning", "checks", "response_time_ms"
+
+puts result["score"]           # => 92
+puts result["verdict"]         # => "valid"
+puts result["recommendation"]  # => "Safe to send"
+
+# Inspect individual checks
+checks = result["checks"]
+puts checks["mx_records"]["valid"]         # => true
+puts checks["disposable"]["is_disposable"] # => false
+puts checks["typo"]["has_typo"]            # => false
+puts checks["smtp"]["valid"]               # => true
+```
+
+### Bulk email validation
+
+```ruby
+# Submit a batch (plan limits apply: free 100, starter 500, pro 1000, etc.)
+job = client.bulk_verify(["a@example.com", "b@example.com", "c@test.com"])
+
+puts job["id"]     # => "bulk_abc123"
+puts job["status"] # => "processing" or "completed"
+puts job["total"]  # => 3
+
+# Each result in the array:
+job["results"].each do |r|
+  puts "#{r["email"]} — #{r["verdict"]} (score: #{r["score"]})"
+end
+```
+
+### Retrieve a bulk job
+
+```ruby
+detail = client.get_bulk_job("bulk_abc123")
+
+puts detail["status"]       # => "completed"
+puts detail["total_emails"] # => 3
+puts detail["results"].length
+```
+
+### List recent bulk jobs
+
+```ruby
+jobs = client.list_bulk_jobs
+
+jobs.each do |j|
+  puts "#{j["id"]} — #{j["status"]} (#{j["processed"]}/#{j["total_emails"]})"
+end
+```
+
+## Error Handling
+
+All API errors raise `MailSentry::Error`, which includes the HTTP status code:
+
+```ruby
+begin
+  client.verify("bad-input")
+rescue MailSentry::Error => e
+  puts e.message      # => "Invalid email format"
+  puts e.status_code   # => 422
+end
+```
+
+Common status codes:
+
+| Code | Meaning |
+|------|---------|
+| 401  | Invalid or missing API key |
+| 422  | Validation error (bad input) |
+| 429  | Rate limit exceeded |
+| 500  | Server error |
+
+## API Reference
+
+| Method | HTTP | Path | Returns |
+|--------|------|------|---------|
+| `verify(email)` | POST | `/api/v1/verify` | `Hash` |
+| `bulk_verify(emails, filename:)` | POST | `/api/v1/bulk` | `Hash` |
+| `get_bulk_job(id)` | GET | `/api/v1/bulk/{id}` | `Hash` |
+| `list_bulk_jobs` | GET | `/api/v1/bulk` | `Array<Hash>` |
+
+## Links
+
+- [Documentation](https://mailsentry.dev/docs)
+- [Dashboard & API keys](https://mailsentry.dev/dashboard)
+- [Sign up (free, no credit card)](https://mailsentry.dev/signup)

data/lib/mailsentry/client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module MailSentry
+  # HTTP client for the MailSentry email-validation API.
+  #
+  #   client = MailSentry::Client.new(api_key: "ms_live_...")
+  #   result = client.verify("user@example.com")
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://mailsentry.dev"
+    DEFAULT_TIMEOUT  = 30 # seconds
+
+    # @param api_key  [String]  your MailSentry API key.
+    # @param base_url [String]  API base URL (override for testing / self-hosted).
+    # @param timeout  [Integer] request timeout in seconds.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      raise ArgumentError, "API key is required" if api_key.nil? || api_key.strip.empty?
+
+      @api_key  = api_key
+      @base_url = base_url.chomp("/")
+      @timeout  = timeout
+    end
+
+    # Validate a single email address.
+    #
+    # @param email [String] the email address to validate.
+    # @return [Hash] validation result with score, verdict, checks, etc.
+    # @raise [MailSentry::Error] on non-2xx responses.
+    def verify(email)
+      post("/api/v1/verify", { email: email })
+    end
+
+    # Submit a batch of emails for bulk validation.
+    #
+    # @param emails   [Array<String>] list of email addresses.
+    # @param filename [String, nil]   optional label for the job.
+    # @return [Hash] bulk job response with id, status, total, and results.
+    # @raise [MailSentry::Error] on non-2xx responses.
+    def bulk_verify(emails, filename: nil)
+      body = { emails: emails }
+      body[:filename] = filename if filename
+      post("/api/v1/bulk", body)
+    end
+
+    # Retrieve details and results of a bulk validation job.
+    #
+    # @param id [String] the bulk job ID.
+    # @return [Hash] job details including results array.
+    # @raise [MailSentry::Error] on non-2xx responses.
+    def get_bulk_job(id)
+      get("/api/v1/bulk/#{id}")
+    end
+
+    # List recent bulk validation jobs (up to 20).
+    #
+    # @return [Array<Hash>] list of bulk job summaries.
+    # @raise [MailSentry::Error] on non-2xx responses.
+    def list_bulk_jobs
+      data = get("/api/v1/bulk")
+      data["jobs"]
+    end
+
+    private
+
+    # ---- HTTP helpers -------------------------------------------------------
+
+    def get(path)
+      request(Net::HTTP::Get, path)
+    end
+
+    def post(path, body)
+      request(Net::HTTP::Post, path, body)
+    end
+
+    def request(verb_class, path, body = nil)
+      uri = URI("#{@base_url}#{path}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      req = verb_class.new(uri)
+      req["Content-Type"] = "application/json"
+      req["X-API-Key"]    = @api_key
+      req.body = JSON.generate(body) if body
+
+      res = http.request(req)
+
+      parsed = begin
+        JSON.parse(res.body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      unless res.is_a?(Net::HTTPSuccess)
+        message = parsed&.dig("error") || "Request failed: #{res.code}"
+        raise MailSentry::Error.new(message, res.code.to_i)
+      end
+
+      parsed
+    end
+  end
+end

data/lib/mailsentry/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MailSentry
+  # Raised when the MailSentry API returns a non-2xx response.
+  class Error < StandardError
+    # @return [Integer] HTTP status code from the API response.
+    attr_reader :status_code
+
+    # @param message [String] human-readable error description.
+    # @param status_code [Integer] HTTP status code.
+    def initialize(message, status_code)
+      @status_code = status_code
+      super(message)
+    end
+  end
+end

data/lib/mailsentry/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MailSentry
+  VERSION = "1.0.0"
+end

data/lib/mailsentry.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "mailsentry/version"
+require_relative "mailsentry/error"
+require_relative "mailsentry/client"
+
+module MailSentry
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: mailsentry
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- MailSentry
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-09 00:00:00.000000000 Z
+dependencies: []
+description: Validate emails in real time with 8 layers of checks including syntax,
+  MX, disposable, role-based, typo, SMTP, gibberish, and spam-trap detection.
+email:
+- support@mailsentry.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/mailsentry.rb
+- lib/mailsentry/client.rb
+- lib/mailsentry/error.rb
+- lib/mailsentry/version.rb
+homepage: https://mailsentry.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mailsentry.dev
+  source_code_uri: https://github.com/mailsentry/mailsentry-ruby
+  documentation_uri: https://mailsentry.dev/docs
+  changelog_uri: https://github.com/mailsentry/mailsentry-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the MailSentry email-validation API
+test_files: []