postmail_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a30c976e7a59b089ec5ed4ce4e7efdf8b734433588e021d91f58f1b61c5e6588
+  data.tar.gz: b8e359dc9348ee1ee54af9a02cb692b68f1d57badcd131e646deab645e4344c2
+SHA512:
+  metadata.gz: ad6a4510ea30befbd59ab3704b46a3eada3becf11b34dc46ab3768a86f0e82b598b754c23d20f68c87993fab82a3c3a21b6772613f3ecdf89cd47bb4c273b199
+  data.tar.gz: 036a7cd3fa7c8e766a2ecc589de70e2e06839abce07057850ca6684ece45da21c4afbf9c2d7fc5ef5b5ca17cda21e5d5258043ffd2d35b59769c01553f0390f0

data/README.md

@@ -0,0 +1,95 @@
+# Postmail
+
+Postmail est une gem Ruby qui fournit un mécanisme flexible d’envoi d’e‑mails pour Ruby on Rails ou tout projet utilisant Action Mailer.  La gem propose deux méthodes d’expédition : soit par **SMTP**, soit par une **API HTTP**.  Tous les paramètres de connexion et le choix de la méthode d’envoi se pilotent via des variables d’environnement afin de simplifier la configuration lors du déploiement.
+
+## Installation
+
+Dans votre `Gemfile`, ajoutez :
+
+```ruby
+gem "postmail", path: "path/to/postmail"
+```
+
+Puis exécutez `bundle install` pour installer la gem.
+
+## Utilisation dans Rails
+
+Postmail enregistre deux méthodes de livraison personnalisées pour Action Mailer : `:postmail_smtp` et `:postmail_api`.  La gem est livrée avec un **Railtie** qui détecte Rails et configure automatiquement Action Mailer en fonction des variables d’environnement ci‑dessous.  En pratique, il suffit de définir vos variables d’environnement et de vous assurer que la gem est chargée.
+
+Si vous souhaitez configurer explicitement la gem (par exemple hors de Rails), vous pouvez appeler :
+
+```ruby
+require "postmail"
+Postmail.configure
+```
+
+Cette méthode lit les variables d’environnement, enregistre les méthodes de livraison et définit la méthode d’envoi par défaut (`delivery_method`) sur Action Mailer.
+
+### Variables d’environnement
+
+Toutes les options de configuration se font via des variables d’environnement, ce qui permet de modifier le comportement sans changer le code.  Voici les variables reconnues :
+
+| Variable | Description | Valeur par défaut |
+|---------|-------------|------------------|
+| `POSTMAIL_DELIVERY_METHOD` | Choix de la méthode d’envoi : `smtp` (envoi via serveur SMTP) ou `api` (envoi via appel HTTP). | `smtp` |
+| `POSTMAIL_DISABLE_RAILS_SMTP` | Lorsque défini à `true`, Postmail désactive les paramètres SMTP par défaut de Rails (`ActionMailer::Base.smtp_settings`) pour éviter des retours en arrière accidentels. Utiliser cette option est recommandé si vous envoyez exclusivement via l’API. | `false` |
+| `POSTMAIL_API_ENDPOINT` | URL complète de l’endpoint HTTP pour l’envoi par API (par exemple `https://postal.exanora.com/api/v1/send/message`). Obligatoire si `POSTMAIL_DELIVERY_METHOD=api`. | – |
+| `POSTMAIL_API_KEY` | Clé d’API utilisée pour authentifier les requêtes HTTP (envoyée dans l’en‑tête `X-Server-API-Key`). | – |
+| `POSTMAIL_API_TIMEOUT` | Temps d’attente maximum en secondes lors de l’appel HTTP. | `10` |
+| `POSTMAIL_SMTP_HOST` | Nom d’hôte du serveur SMTP (ex : `smtp.exemple.com`). Obligatoire si `POSTMAIL_DELIVERY_METHOD=smtp`. | – |
+| `POSTMAIL_SMTP_PORT` | Port du serveur SMTP. | `587` |
+| `POSTMAIL_SMTP_USERNAME` | Nom d’utilisateur pour l’authentification SMTP. Laisser vide pour une connexion sans authentification. | `nil` |
+| `POSTMAIL_SMTP_PASSWORD` | Mot de passe pour l’authentification SMTP. | `nil` |
+| `POSTMAIL_SMTP_AUTHENTICATION` | Type d’authentification SMTP : `plain`, `login` ou `cram_md5`. | `plain` |
+| `POSTMAIL_SMTP_ENABLE_STARTTLS_AUTO` | Active STARTTLS. Mettre `false` pour désactiver. | `true` |
+| `POSTMAIL_SMTP_SSL` | Lorsque défini à `true`, Postmail établit une connexion SSL/TLS implicite (comme un port 465). | `false` |
+| `POSTMAIL_SMTP_OPEN_TIMEOUT` | Durée maximale (en secondes) pour établir la connexion SMTP. | `30` |
+| `POSTMAIL_SMTP_READ_TIMEOUT` | Durée maximale (en secondes) pour la lecture des réponses SMTP. | `30` |
+
+### Désactiver le SMTP par défaut de Rails
+
+Rails utilise un mécanisme SMTP par défaut si aucune méthode d’envoi n’est explicitement configurée.  Pour éviter toute utilisation accidentelle du SMTP intégré lorsque vous utilisez Postmail, définissez :
+
+```sh
+POSTMAIL_DISABLE_RAILS_SMTP=true
+```
+
+Lorsque cette variable est à `true`, Postmail réinitialise `ActionMailer::Base.smtp_settings` à un hash vide et définit `ActionMailer::Base.delivery_method` sur `:postmail_api` ou `:postmail_smtp` en fonction de `POSTMAIL_DELIVERY_METHOD`.
+
+### Exemple de configuration
+
+Pour envoyer via l’API HTTP :
+
+```sh
+POSTMAIL_DELIVERY_METHOD=api
+POSTMAIL_API_ENDPOINT=https://postal.exanora.com/api/v1/send/message
+POSTMAIL_API_KEY=your_api_key
+POSTMAIL_DISABLE_RAILS_SMTP=true
+```
+
+Pour envoyer via SMTP :
+
+```sh
+POSTMAIL_DELIVERY_METHOD=smtp
+POSTMAIL_SMTP_HOST=smtp.exemple.com
+POSTMAIL_SMTP_PORT=2587
+POSTMAIL_SMTP_USERNAME=user
+POSTMAIL_SMTP_PASSWORD=secret
+POSTMAIL_SMTP_AUTHENTICATION=login
+POSTMAIL_SMTP_ENABLE_STARTTLS_AUTO=true
+POSTMAIL_DISABLE_RAILS_SMTP=false
+```
+
+## Fonctionnement
+
+Lorsque la méthode d’envoi est `api`, Postmail sérialise votre message et l’envoie en `POST` vers l’endpoint HTTP.  Le corps de la requête est JSON et inclut les adresses, le sujet, les corps texte/HTML et les pièces jointes (encodées en Base64).  La clé API est transmise via l’en‑tête `X-Server-API-Key`.
+
+Lorsque la méthode d’envoi est `smtp`, Postmail utilise les paramètres SMTP renseignés pour établir la connexion avec le serveur de messagerie via la gem `mail`.  Les options SSL/TLS, timeouts et authentification sont héritées des variables d’environnement.
+
+## Contribuer
+
+Les demandes d’amélioration et les rapports de bogue sont les bienvenus !  Ouvrez une issue ou une pull request sur GitHub à l’adresse <https://github.com/votrecompte/postmail>.
+
+## Licence
+
+Ce projet est distribué sous licence MIT.  Voir le fichier `LICENSE` pour plus de détails.

data/lib/postmail_ruby/configuration.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module PostmailRuby
+  # Configuration holds all settings loaded from environment variables or via configuration block.
+  # It provides helpers to build SMTP settings and determine if default Rails SMTP
+  # configuration should be disabled.
+  class Configuration
+    # Delivery method to use (:smtp or :api)
+    attr_accessor :delivery_method
+    # API endpoint for HTTP delivery
+    attr_accessor :api_endpoint
+    # API key for HTTP delivery (used in X-Server-API-Key header)
+    attr_accessor :api_key
+    # SMTP host
+    attr_accessor :smtp_host
+    # SMTP port (integer)
+    attr_accessor :smtp_port
+    # SMTP username
+    attr_accessor :smtp_username
+    # SMTP password
+    attr_accessor :smtp_password
+    # SMTP authentication type (:plain, :login, etc.)
+    attr_accessor :smtp_authentication
+    # Enable STARTTLS for SMTP (boolean)
+    attr_accessor :smtp_enable_starttls_auto
+    # Use SSL/TLS implicit connection for SMTP (boolean)
+    attr_accessor :smtp_ssl
+    # Domain used for SMTP
+    attr_accessor :smtp_domain
+
+    def initialize
+      # set defaults from environment variables
+      @delivery_method = (ENV['POSTMAIL_DELIVERY_METHOD'] || 'smtp').downcase.to_sym
+      @disable_default_smtp = truthy?(ENV['POSTMAIL_DISABLE_RAILS_SMTP'])
+
+      @api_endpoint = ENV['POSTMAIL_API_ENDPOINT'] || 'https://postal.exanora.com/api/v1/send/message'
+      @api_key      = ENV['POSTMAIL_API_KEY']
+
+      @smtp_host    = ENV['POSTMAIL_SMTP_HOST'] || 'localhost'
+      @smtp_port    = integer_or_nil(ENV['POSTMAIL_SMTP_PORT']) || 25
+      @smtp_username = ENV['POSTMAIL_SMTP_USERNAME']
+      @smtp_password = ENV['POSTMAIL_SMTP_PASSWORD']
+      @smtp_authentication = (ENV['POSTMAIL_SMTP_AUTH'] || 'login').downcase.to_sym
+      @smtp_enable_starttls_auto = truthy?(ENV['POSTMAIL_SMTP_ENABLE_STARTTLS_AUTO'])
+      # If not explicitly set, enable_starttls_auto defaults to true unless SSL is enabled
+      @smtp_enable_starttls_auto = !truthy?(ENV['POSTMAIL_SMTP_SSL']) if @smtp_enable_starttls_auto.nil?
+      @smtp_ssl    = truthy?(ENV['POSTMAIL_SMTP_SSL'])
+      @smtp_domain = ENV['POSTMAIL_SMTP_DOMAIN']
+    end
+
+    # Returns true if the default Rails SMTP configuration should be disabled.
+    # When this is true, Postmail will clear `config.action_mailer.smtp_settings`.
+    def disable_default_smtp?
+      @disable_default_smtp
+    end
+
+    # Compose SMTP settings hash suitable for Mail::SMTP or ActionMailer.
+    def smtp_settings
+      settings = {
+        address: smtp_host, port: smtp_port,
+        user_name: smtp_username, password: smtp_password,
+        authentication: smtp_authentication,
+        enable_starttls_auto: smtp_enable_starttls_auto, ssl: smtp_ssl
+      }
+      settings[:domain] = smtp_domain if smtp_domain
+      # Remove nil values to avoid overriding defaults
+      settings.compact
+    end
+
+    private
+
+    # Convert string to boolean if present, returns nil if value not provided.
+    def truthy?(value)
+      return nil if value.nil? || value.empty?
+
+      case value.downcase
+      when 'true', '1', 'yes', 'y'
+        true
+      when 'false', '0', 'no', 'n'
+        false
+      end
+    end
+
+    # Convert string to integer, returns nil if value is blank or not numeric.
+    def integer_or_nil(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      begin
+        Integer(value)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/postmail_ruby/delivery_method/http.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+
+module PostmailRuby
+  module DeliveryMethod
+    # Implements a delivery method for Action Mailer that sends
+    # messages via the Postal HTTP API. Instead of speaking SMTP
+    # directly, this class packages the email into a JSON payload
+    # and posts it to the configured Postal endpoint. An API key
+    # must be provided via configuration for authentication.
+    class HTTP
+      attr_reader :settings
+
+      # Initialize the HTTP delivery method. Accepts a hash of
+      # options that may override configuration defaults. Options
+      # are stored but not used directly; configuration is read
+      # from Postmail.config for each delivery to ensure the most
+      # current environment variables are respected.
+      #
+      # @param [Hash] options delivery options (currently unused)
+      def initialize(options = {})
+        @settings = options
+      end
+
+      # Deliver a Mail::Message via the Postal API. Builds a JSON
+      # payload including recipients, subject, plain and HTML parts
+      # and attachments. Sends the payload as a POST request with
+      # the API key in the X-Server-API-Key header. Raises an
+      # exception if the request returns a non-success response.
+      #
+      # @param [Mail::Message] mail the message to send
+      def deliver!(mail)
+        config = Postmail.config
+        uri = URI.parse(config.api_endpoint)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.read_timeout = 15
+        http.open_timeout = 5
+
+        request = Net::HTTP::Post.new(uri.request_uri, {
+                                        'Content-Type' => 'application/json',
+                                        'X-Server-API-Key' => config.api_key.to_s
+                                      })
+        request.body = build_payload(mail, config).to_json
+
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "Postal API responded with status #{response.code}: #{response.body}"
+        end
+
+        response
+      end
+
+      private
+
+      # Build a hash representing the JSON payload expected by
+      # Postal's API. Extracts addresses, subject, plain and HTML
+      # bodies and encodes attachments as base64. Null values are
+      # omitted from the final hash for brevity.
+      #
+      # @param [Mail::Message] mail
+      # @param [Postmail::Configuration] config
+      # @return [Hash]
+      def build_payload(mail, _config)
+        {
+          from: extract_sender(mail),
+          to: extract_addresses(mail.to),
+          cc: extract_addresses(mail.cc),
+          bcc: extract_addresses(mail.bcc),
+          subject: mail.subject.to_s,
+          plain_body: extract_part(mail, 'text/plain'),
+          html_body: extract_part(mail, 'text/html'),
+          attachments: build_attachments(mail)
+        }.compact
+      end
+
+      # Extract the sender address. The Mail object may store
+      # from address as an array; we use the first entry. Returns
+      # nil if no sender is specified.
+      def extract_sender(mail)
+        Array(mail.from).first
+      end
+
+      # Convert an array of addresses to a comma-separated string.
+      # Returns nil if the array is blank.
+      def extract_addresses(value)
+        return nil if value.nil? || value.empty?
+
+        Array(value).join(',')
+      end
+
+      # Extract a specific MIME part "../../postmail/delivery_method""."from the message. For
+      # multipart messages, the first matching part "../../postmail/delivery_method""."is returned.
+      # For non-multipart, the body is returned if the MIME type
+      # matches. Returns nil if no matching part "../../postmail/delivery_method""."exists.
+      def extract_part(mail, mime_type)
+        if mail.multipart?
+          mail.parts.find { |p| p.mime_type&.start_with?(mime_type) }
+          part "../../postmail_ruby/delivery_method#{'.'.decoded}"
+        else
+          mail.mime_type&.start_with?(mime_type) ? mail.body.decoded : nil
+        end
+      end
+
+      # Build an array of attachment hashes. Each attachment
+      # includes name, content_type and base64 encoded data. If
+      # there are no attachments the method returns nil to omit
+      # the key from the payload.
+      def build_attachments(mail)
+        return nil if mail.attachments.empty?
+
+        mail.attachments.map do |att|
+          {
+            name: att.filename.to_s,
+            content_type: att.mime_type.to_s,
+            data: Base64.strict_encode64(att.body.decoded)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/postmail_ruby/delivery_method/smtp.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'mail'
+
+module PostmailRuby
+  module DeliveryMethod
+    # Provides a custom SMTP delivery method that reads its
+    # configuration from Postmail::Configuration. This class is
+    # essentially a thin wrapper around Mail::SMTP, passing in
+    # settings derived from environment variables. It allows
+    # Action Mailer to use Postmail configuration seamlessly.
+    class SMTP
+      attr_reader :settings
+
+      # Initialize the SMTP delivery method. Accepts an options
+      # hash which can override the configuration. Options are
+      # merged with configuration on each delivery.
+      #
+      # @param [Hash] options options overriding configuration
+      def initialize(options = {})
+        @settings = options
+      end
+
+      # Delivers a Mail::Message via SMTP. Merges any options
+      # provided during initialization with the configuration's
+      # smtp_settings. Uses Mail::SMTP#deliver! to send the
+      # message.
+      #
+      # @param [Mail::Message] mail the message to send
+      def deliver!(mail)
+        config_settings = Postmail.config.smtp_settings
+        smtp_settings = config_settings.merge(settings)
+        smtp = ::Mail::SMTP.new(smtp_settings)
+        smtp.deliver!(mail)
+      end
+    end
+  end
+end

data/lib/postmail_ruby/railtie.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module PostmailRuby
+  # Railtie for integrating Postmail with Rails. This railtie
+  # registers custom delivery methods with Action Mailer and
+  # configures Action Mailer based on Postmail configuration. It
+  # also offers an option to disable the default SMTP settings
+  # configured by Rails, allowing Postmail to be the sole mail
+  # provider in a Rails application.
+  class Railtie < ::Rails::Railtie
+    initializer 'postmail_ruby.initialize' do
+      ActiveSupport.on_load(:action_mailer) do
+        # Register our delivery methods
+        ActionMailer::Base.add_delivery_method :postmail_smtp, Postmail::DeliveryMethod::SMTP
+        ActionMailer::Base.add_delivery_method :postmail_api, Postmail::DeliveryMethod::HTTP
+
+        # Determine which delivery method to use based on configuration
+        delivery_method = Postmail.config.delivery_method
+        ActionMailer::Base.delivery_method = case delivery_method
+                                             when :api
+                                               :postmail_api
+                                             else
+                                               :postmail_smtp
+                                             end
+
+        # If using SMTP, apply our SMTP settings and optionally
+        # clear any default Rails SMTP settings. The
+        # disable_default_smtp? flag removes Rails SMTP settings
+        # before applying Postmail settings.
+        if delivery_method == :smtp
+          if PostmailRuby.config.disable_default_smtp?
+            # Clear any pre-existing SMTP settings so they do not
+            # interfere with Postmail's configuration
+            ActionMailer::Base.smtp_settings = {}
+          end
+          ActionMailer::Base.smtp_settings = PostmailRuby.config.smtp_settings
+        end
+      end
+    end
+  end
+end

data/lib/postmail_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PostmailRuby
+  # Gem version constant
+  VERSION = '0.1.0'
+end

data/lib/postmail_ruby.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'postmail_ruby/version'
+require_relative 'postmail_ruby/configuration'
+
+# Main entry point for the Postmail gem. This module exposes
+# configuration and helper methods to integrate the gem into a
+# Ruby on Rails application. When loaded in a Rails environment,
+# a Railtie is required automatically to register custom delivery
+# methods with Action Mailer.
+module PostmailRuby
+  class << self
+    # Accessor for the configuration instance. When first called
+    # a new Configuration object is created and memoized. This
+    # object reads environment variables to determine how Postmail
+    # should behave (API vs SMTP, credentials, endpoints, etc.).
+    #
+    # @return [Postmail::Configuration]
+    attr_accessor :configuration
+
+    # Yields the configuration instance to a block so that callers
+    # can override defaults at runtime. If no block is given the
+    # current configuration is returned. This is the primary API
+    # used to change settings in an initializer.
+    #
+    # @example Override the API endpoint
+    #   Postmail.configure do |config|
+    #     config.api_endpoint = "https://my-postal.example/api/v1/send/message"
+    #   end
+    #
+    # @yieldparam [Postmail::Configuration] configuration
+    # @return [Postmail::Configuration]
+    def configure
+      self.configuration ||= Configuration.new
+      return configuration unless block_given?
+
+      yield(configuration)
+      configuration
+    end
+
+    # Ensures that a configuration instance exists. If the
+    # configuration has not been initialized then a new one is
+    # created. This method should be used internally when a
+    # configuration is required.
+    #
+    # @return [Postmail::Configuration]
+    def config
+      self.configuration ||= Configuration.new
+    end
+  end
+end
+
+# Require delivery method classes. These require statements are
+# placed outside of the Postmail module definition so that they
+# are loaded when the gem is required. They rely on Postmail
+# configuration, so configuration must be loaded first.
+require_relative 'postmail_ruby/delivery_method/http'
+require_relative 'postmail_ruby/delivery_method/smtp'
+
+# Load the Railtie only if Rails is defined. The Railtie is
+# responsible for registering delivery methods and setting up
+# Action Mailer configuration based on environment variables.
+require_relative 'postmail_ruby/railtie' if defined?(Rails)

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: postmail_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DAKIN Judicaël
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-09-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Postmail is a simple gem that adds custom Action Mailer delivery methods
+  allowing you to send email via either SMTP or an HTTP API. The delivery method and
+  all settings are configurable via environment variables so it can be easily switched
+  at runtime without code changes.
+email:
+- d.j.bidossessi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/postmail_ruby.rb
+- lib/postmail_ruby/configuration.rb
+- lib/postmail_ruby/delivery_method/http.rb
+- lib/postmail_ruby/delivery_method/smtp.rb
+- lib/postmail_ruby/railtie.rb
+- lib/postmail_ruby/version.rb
+homepage: https://postmail.exanora.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key: 
+specification_version: 4
+summary: Delivery methods for sending mail via SMTP or HTTP using environment variables
+test_files: []