enkimail 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5ca7bbe0f36972c0f3291cf76789a7b09743c58f1730fae9f722c7d19c9bd7f
+  data.tar.gz: 8f6ddd5b31ca53ed0f198a74a982f7ffe72c0ee9b3b9f10b79aa681ebe71323b
+SHA512:
+  metadata.gz: 9250bafefcc6d06f1e925532031981fd498e077587f42931af275b55de44495b466249dfab69d4b199181c1baf6e63fc8c0903f5ff5fd8493f0d9ff95ecbf979
+  data.tar.gz: cf20324020a395c486b5863216c98ace782703b3c490c2b12cb7904d38484b7728a9529e0fb42d7351ef95e1176b20220e455f34acc41d75d7176d752d5f391e

data/.rspec_status

@@ -0,0 +1,6 @@
+example_id                                     | status | run_time        |
+---------------------------------------------- | ------ | --------------- |
+./spec/enkimail/client_spec.rb[1:1:1]          | passed | 0.39165 seconds |
+./spec/enkimail/client_spec.rb[1:1:2]          | passed | 0.02099 seconds |
+./spec/enkimail/delivery_method_spec.rb[1:1:1] | passed | 0.07246 seconds |
+./spec/enkimail/delivery_method_spec.rb[1:1:2] | passed | 0.00045 seconds |

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Albert Oliva
+
+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,117 @@
+# Enkimail Ruby Gem
+
+[![Gem Version](https://badge.fury.io/rb/enkimail.svg)](https://badge.fury.io/rb/enkimail)
+
+`enkimail` is the official gem for integrating [Enkimail](https://enkimail.com) transactional email service with Ruby on Rails. It allows you to send emails using Enkimail's infrastructure simply by configuring the ActionMailer `delivery_method`.
+
+## Features
+
+*   **Native Rails Integration:** Automatically registers as an ActionMailer delivery method.
+*   **Multipart Support:** Automatically handles HTML and plain text email bodies.
+*   **Attachments:** Built-in support for sending attachments (automatically Base64 encoded for the API).
+*   **Flexible Configuration:** Allows defining a `base_url` for testing in development or staging environments.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'enkimail'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it manually:
+
+    $ gem install enkimail
+
+## Prerequisites
+
+Before using the gem, ensure that:
+1.  **Verified Domain:** Your sending domain must be verified in the Enkimail dashboard.
+2.  **Verified Sender:** The `from` email address you use must be a verified sender in your Enkimail account.
+
+Emails sent from unverified domains or senders will be rejected by the API.
+
+## Configuration in Rails
+
+To use Enkimail as your email provider, edit your environment configuration file (e.g., `config/environments/production.rb`):
+
+```ruby
+Rails.application.configure do
+  # ...
+  config.action_mailer.delivery_method = :enkimail
+  config.action_mailer.enkimail_settings = {
+    api_key: ENV['ENKIMAIL_API_KEY']
+  }
+
+  # Optional: Configure a global 'from' address
+  # This address MUST be a verified sender in your Enkimail dashboard.
+  config.action_mailer.default_options = { from: 'no-reply@yourdomain.com' }
+end
+```
+
+### Configuration Options
+
+| Option | Description | Required |
+| :--- | :--- | :--- |
+| `api_key` | Your Enkimail API Key. | Yes |
+| `base_url` | API base URL (defaults to `https://api.enkimail.com`). | No |
+
+## Usage
+
+You can set the `from` address globally in your `ApplicationMailer` or specifically in each mailer method. Remember that Enkimail requires the sender to be verified.
+
+### Setting a Default Sender
+
+```ruby
+class ApplicationMailer < ActionMailer::Base
+  default from: 'info@yourdomain.com'
+  layout 'mailer'
+end
+```
+
+### Overriding the Sender in a Specific Mailer
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email(user)
+    @user = user
+    mail(
+      to: @user.email,
+      subject: 'Welcome to Enkimail',
+      from: 'onboarding@yourdomain.com' # Must be a verified sender
+    )
+  end
+end
+```
+
+### Sending Attachments
+
+The gem handles attachment processing automatically:
+
+```ruby
+def invoice_email(user, invoice_pdf)
+  attachments['invoice.pdf'] = invoice_pdf
+  mail(to: user.email, subject: 'Your Invoice')
+end
+```
+
+## Local Development
+
+If you are developing the Enkimail API locally and want to test the gem against your local Rails instance, you can configure the `base_url`:
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.delivery_method = :enkimail
+config.action_mailer.enkimail_settings = {
+  api_key: 'test_key',
+  base_url: 'http://localhost:3000'
+}
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/enkimail/client.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Enkimail
+  class Client
+    DEFAULT_BASE_URL = "https://api.enkimail.com"
+
+    attr_reader :api_key, :base_url
+
+    def initialize(api_key, base_url: nil)
+      @api_key = api_key
+      @base_url = (base_url || DEFAULT_BASE_URL).chomp("/")
+    end
+
+    def deliver(mail)
+      response = connection.post("/api/v1/transactional_emails") do |req|
+        req.body = build_payload(mail)
+      end
+
+      handle_response(response)
+    rescue Faraday::Error => e
+      raise Error, "Enkimail Connection Error: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |conn|
+        conn.request :json
+        conn.headers["Authorization"] = "Bearer #{api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def build_payload(mail)
+      payload = {
+        from: (mail.from || []).join(", "),
+        to: (mail.to || []).join(", "),
+        cc: (mail.cc || []).join(", "),
+        bcc: (mail.bcc || []).join(", "),
+        subject: mail.subject,
+        attachments: build_attachments(mail)
+      }
+
+      if mail.multipart?
+        payload[:body] = mail.text_part&.body&.decoded
+        payload[:html_body] = mail.html_part&.body&.decoded
+      else
+        if mail.content_type =~ /html/
+          payload[:html_body] = mail.body&.decoded
+        else
+          payload[:body] = mail.body&.decoded
+        end
+      end
+
+      # Clean up nil values
+      payload.compact
+    end
+
+    def build_attachments(mail)
+      return nil unless mail.attachments.any?
+
+      mail.attachments.map do |attachment|
+        {
+          name: attachment.filename,
+          content: [attachment.body.decoded].pack("m0"), # Base64
+          content_type: attachment.content_type.split(";").first
+        }
+      end
+    end
+
+    def handle_response(response)
+      return response if response.success?
+
+      begin
+        error_info = JSON.parse(response.body)
+        error_message = error_info["error"] || error_info["errors"] || "Unknown API error"
+      rescue JSON::ParserError
+        error_message = "HTTP #{response.status}: #{response.body[0..100]}"
+      end
+
+      raise Error, "Enkimail API Error (#{response.status}): #{error_message}"
+    end
+  end
+end

data/lib/enkimail/delivery_method.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module Enkimail
+  class DeliveryMethod
+    attr_accessor :settings
+
+    def initialize(settings)
+      @settings = settings
+    end
+
+    def deliver!(mail)
+      validate_settings!
+      client = Client.new(settings[:api_key], base_url: settings[:base_url])
+      client.deliver(mail)
+    end
+
+    private
+
+    def validate_settings!
+      raise Error, "Enkimail API Key is missing. Please set config.action_mailer.enkimail_settings = { api_key: '...' }" if settings[:api_key].nil? || settings[:api_key].empty?
+    end
+  end
+end

data/lib/enkimail/version.rb

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

data/lib/enkimail.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "enkimail/version"
+require_relative "enkimail/client"
+require_relative "enkimail/delivery_method"
+
+module Enkimail
+  class Error < StandardError; end
+
+  # Rails integration
+  if defined?(ActionMailer)
+    ActionMailer::Base.add_delivery_method :enkimail, Enkimail::DeliveryMethod
+  end
+end

data/sig/enkimail.rbs

@@ -0,0 +1,4 @@
+module Enkimail
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/spec/enkimail/client_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Enkimail::Client do
+  let(:api_key) { "test_api_key" }
+  let(:client) { described_class.new(api_key) }
+  let(:mail) do
+    Mail.new do
+      from    "Sender Name <sender@example.com>"
+      to      "Recipient Name <recipient@example.com>"
+      subject "Test Subject"
+      body    "Hello world"
+      
+      add_file filename: "test.txt", content: "test content"
+    end
+  end
+
+  describe "#deliver" do
+    let(:endpoint) { "https://api.enkimail.com/api/v1/transactional_emails" }
+
+    before do
+      stub_request(:post, endpoint)
+        .with(
+          headers: {
+            "Authorization" => "Bearer #{api_key}",
+            "Content-Type" => "application/json"
+          }
+        )
+        .to_return(status: 200, body: { status: "success" }.to_json)
+    end
+
+    it "sends the correct payload to the API" do
+      client.deliver(mail)
+
+      expect(a_request(:post, endpoint).with { |req|
+        payload = JSON.parse(req.body)
+        expect(payload["from"]).to eq("Sender Name <sender@example.com>")
+        expect(payload["to"]).to eq("Recipient Name <recipient@example.com>")
+        expect(payload["subject"]).to eq("Test Subject")
+        expect(payload["body"]).to eq("Hello world")
+        expect(payload["attachments"]).to be_an(Array)
+        expect(payload["attachments"].first["name"]).to eq("test.txt")
+        expect(payload["attachments"].first["content"]).to eq([ "test content" ].pack("m0"))
+        expect(payload["attachments"].first["content_type"]).to eq("text/plain")
+      }).to have_been_made.once
+    end
+
+    it "handles API errors correctly" do
+      stub_request(:post, endpoint).to_return(
+        status: 401,
+        body: { error: "Invalid API Key" }.to_json
+      )
+
+      expect {
+        client.deliver(mail)
+      }.to raise_error(Enkimail::Error, /Invalid API Key/)
+    end
+  end
+end

data/spec/enkimail/delivery_method_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Enkimail::DeliveryMethod do
+  let(:settings) { { api_key: "abc_123" } }
+  let(:delivery_method) { described_class.new(settings) }
+  let(:mail) { Mail.new }
+
+  describe "#deliver!" do
+    it "initializes the client and calls deliver" do
+      client_double = instance_double(Enkimail::Client)
+      expect(Enkimail::Client).to receive(:new).with("abc_123", base_url: nil).and_return(client_double)
+      expect(client_double).to receive(:deliver).with(mail)
+
+      delivery_method.deliver!(mail)
+    end
+
+    it "raises error if api_key is missing" do
+      bad_delivery = described_class.new({})
+      expect {
+        bad_delivery.deliver!(mail)
+      }.to raise_error(Enkimail::Error, /API Key is missing/)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "enkimail"
+require "webmock/rspec"
+require "mail"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: enkimail
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Albert Oliva
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Integrate Rails with Enkimail API to send emails seamlessly.
+email:
+- albert.oliva@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec_status"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/enkimail.rb
+- lib/enkimail/client.rb
+- lib/enkimail/delivery_method.rb
+- lib/enkimail/version.rb
+- sig/enkimail.rbs
+- spec/enkimail/client_spec.rb
+- spec/enkimail/delivery_method_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/enkimail/enkimail-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/enkimail/enkimail-ruby
+  source_code_uri: https://github.com/enkimail/enkimail-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Enkimail delivery method for ActionMailer
+test_files: []