mailchannels-email-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f503dd4bf6d415eebb3c7f6ebc5f4acc7caee1d81ba34b5239bc1e4624c7d6c
+  data.tar.gz: 1626a60d75bed6e350f40f074c97aba5cd50e04056f6d3272e3e8a6d63cad522
+SHA512:
+  metadata.gz: f464babb4c98ec3100a60b447e2374fff0065c9d7599aeb7ce86a6a5ecc2d09989e505f8f26e9c47b52da9450681a9dd4c1454d405efd21f41922b18d772beb8
+  data.tar.gz: 50cda827d1c96c571be8cff22cc79bdc21c0d7f6977aa1963c17ca3d5c0179e34f62d947f2b753cf4710c5c4f8dafd98c0f4bf350219a770f164f932e8265bcf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailChannels Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# MailChannels Email API Ruby client
+
+Published on RubyGems as [`mailchannels-email-api`](https://rubygems.org/gems/mailchannels-email-api).
+This repository is the public development source.
+Support: dev@mailchannels.com. Report reproducible bugs through this repository’s issues.
+
+This Ruby 3.2+ client calls the current MailChannels Email API directly with an
+API key. It accepts the API's full send payload, including personalizations,
+plain text or HTML content, attachments, and custom headers. It does not need a
+Cloudflare Worker. It is a sending client, not an Action Mailer delivery backend.
+
+## Try a validation request
+
+Install the gem:
+
+```sh
+gem install mailchannels-email-api
+```
+
+Provide `MAILCHANNELS_API_KEY` through your environment or secret store. Configure
+your sender domain and use an allowed recipient. The free plan permits 100
+emails/day and restricts recipients to verified account users until a payment
+method is added.
+
+```ruby
+require 'mailchannels/email_api'
+
+client = MailChannels::EmailAPI::Client.new
+message = {
+  from: { email: ENV.fetch('MAILCHANNELS_SENDER') },
+  personalizations: [
+    { to: [{ email: ENV.fetch('MAILCHANNELS_RECIPIENT') }] }
+  ],
+  subject: 'MailChannels Ruby validation',
+  content: [{ type: 'text/plain', value: 'Validate this message without sending.' }]
+}
+
+result = client.validate_email(message)
+puts result.validated? # HTTP 200, no email sent
+```
+
+To send deliberately, call `client.send_email(message)`. An HTTP 202 result has
+`accepted? == true`; it means accepted for processing, not delivered. A dry run
+is HTTP 200 and never reports acceptance. Unexpected statuses, including
+redirects, raise `MailChannels::EmailAPI::APIError` with a `status` attribute.
+
+Payloads use the [API's JSON schema](https://docs.mailchannels.com/email-api.yaml)
+without shorthand conversion. Both string and symbol Hash keys serialize to
+JSON keys. See the [API documentation](https://docs.mailchannels.com/email-api/overview)
+for attachment encoding and other supported fields.
+
+## Failure handling and lifecycle
+
+The client opens and closes an HTTPS session per call. TLS peer verification is
+enabled. Connect timeout is 10 seconds; read and write timeouts are 30 seconds
+each. These are I/O timeouts, not a total request deadline. It does not follow
+redirects, use environment proxies, or automatically retry requests.
+
+An ambiguous transport failure can occur after the server accepts a message.
+Check delivery records before retrying. `TransportError` has a sanitized message
+and does not retain the underlying exception as its cause. API error messages
+contain the HTTP status rather than response bodies. Client inspection redacts
+the API key; application code should also avoid logging requests or payloads.
+
+Ruby argument/JSON serialization errors propagate to the caller before network
+I/O. Use a separate client for each account's key. In Rails, call this client
+from your application service or job; it does not change `ActionMailer` settings.
+
+## Test and package
+
+```sh
+bundle install
+bundle exec ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |file| require_relative file }'
+gem build mailchannels-email-api.gemspec
+```
+
+Unit tests replace the HTTP session; six native transport tests use a local TLS server with
+synthetic credentials and messages. They exercise the real Net::HTTP transport, preserve API
+hostname verification, and route only the expected API socket to loopback. Native tests cover
+empty 202, dry-run 200, untrusted CA, hostname mismatch, redirects, HTTP errors and disconnect after
+receipt. No real API request or email is sent. These checks do not replace separately authorized provider validation. See [RELEASING.md](RELEASING.md) for the release gates.
+Bundler may compile the `json` dependency; development containers need a C
+compiler and make (for example, Debian's `build-essential` package).

data/lib/mailchannels/email_api.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+
+module MailChannels
+  # Direct HTTPS access to the MailChannels Email API send endpoint.
+  module EmailAPI
+    VERSION = '0.1.0'
+
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class TransportError < Error; end
+
+    # HTTP errors deliberately omit response bodies and credentials.
+    class APIError < Error
+      attr_reader :status
+
+      def initialize(status)
+        @status = status
+        super("MailChannels request failed (HTTP #{status})")
+      end
+    end
+
+    # Acceptance is not delivery. A validation result never represents a send.
+    class Result
+      attr_reader :status
+
+      def initialize(status, dry_run)
+        @status = status
+        @dry_run = dry_run
+        freeze
+      end
+
+      def validated?
+        @dry_run && status == 200
+      end
+
+      def accepted?
+        !@dry_run && status == 202
+      end
+    end
+
+    class Client
+      HOST = 'api.mailchannels.net'
+      PATH = '/tx/v1/send'
+
+      # Credentials are copied so caller mutation cannot alter this client.
+      def initialize(api_key: ENV['MAILCHANNELS_API_KEY'])
+        unless api_key.is_a?(String) && !api_key.strip.empty? && !api_key.match?(/[\r\n]/)
+          raise ConfigurationError, 'Set MAILCHANNELS_API_KEY or pass a nonempty api_key'
+        end
+
+        @api_key = api_key.dup.freeze
+      end
+
+      def inspect
+        "#<#{self.class} api_key=[REDACTED]>"
+      end
+      alias to_s inspect
+
+      # Accepts the API's full JSON payload: personalizations, content,
+      # attachments, headers and other documented send fields pass through.
+      # No redirects or retries are performed, including on ambiguous failures.
+      def send_email(payload, dry_run: false)
+        raise ArgumentError, 'payload must be a Hash' unless payload.is_a?(Hash)
+        unless dry_run.equal?(true) || dry_run.equal?(false)
+          raise ArgumentError, 'dry_run must be true or false'
+        end
+
+        request = Net::HTTP::Post.new(dry_run ? "#{PATH}?dry-run=true" : PATH)
+        request['Content-Type'] = 'application/json'
+        request['Accept'] = 'application/json'
+        request['X-Api-Key'] = @api_key
+        request['User-Agent'] = "mailchannels-email-api-ruby/#{VERSION}"
+        request.body = JSON.generate(payload)
+
+        http = Net::HTTP.new(HOST, 443, nil)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.open_timeout = 10
+        http.read_timeout = 30
+        http.write_timeout = 30
+        http.max_retries = 0
+        response = http.start { |connection| connection.request(request) }
+        status = response.code.to_i
+        expected_status = dry_run ? 200 : 202
+        raise APIError, status unless status == expected_status
+
+        Result.new(status, dry_run)
+      rescue Timeout::Error, SocketError, SystemCallError, IOError,
+             OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError
+        raise TransportError,
+              'MailChannels transport failed; delivery status may be unknown. No retry was attempted.',
+              cause: nil
+      end
+
+      def validate_email(payload)
+        send_email(payload, dry_run: true)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: mailchannels-email-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MailChannels Corporation
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: Direct HTTPS client with API-key authentication, dry-run validation,
+  explicit acceptance status, bounded I/O timeouts, and no automatic retries.
+email:
+- dev@mailchannels.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mailchannels/email_api.rb
+homepage: https://www.mailchannels.com/email-api/
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mailchannels/mailchannels-email-api-ruby
+  bug_tracker_uri: https://github.com/mailchannels/mailchannels-email-api-ruby/issues
+  documentation_uri: https://docs.mailchannels.com/email-api/overview
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Send and validate transactional email through the MailChannels Email API.
+test_files: []