ms-graph-mailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b3570e71f901eb9a4113918ff258b9027f1cf1c06fe8cd01f479761aec65ab4
+  data.tar.gz: 26faf075b68963e20d478fd5813eb384a848a6beeb1467ed2eae16da1c166199
+SHA512:
+  metadata.gz: ba486608590ae404c6bc89056b1792664e23023de730776241f0c4ee53d858cbc72aaba869bf76722c66c78eadd7ebc2d68fda4712d0a44c9ee00377dbf72265
+  data.tar.gz: '097c8be2986508a0c0cf8182358135d9ca0490c6a81380ac3a9c66d668c4dee4f9e498c1e230f429fc389dac022cb9dcb955c12e5d8d2e0e500d2e4f84e59aee'

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-15
+
+### Added
+
+- Initial release of ms-graph-mailer gem
+- ActionMailer delivery method for Microsoft Graph API
+- OAuth 2.0 client credentials flow authentication
+- Support for HTML and plain text emails
+- Support for attachments (file attachments)
+- Support for CC, BCC, and Reply-To recipients
+- Comprehensive error handling with custom exception classes
+- Configurable SSL verification
+- Logging support
+- Complete documentation and examples
+
+### Features
+
+- `MsGraphMailer::DeliveryMethod` - Main delivery method class
+- `MsGraphMailer::TokenService` - OAuth token management
+- Configuration system for tenant, client credentials
+- Integration with Rails logger
+
+[0.1.0]: https://github.com/zauberware/ms-graph-mailer/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zauberware Technologies GmbH
+
+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,139 @@
+# Ms Graph Mailer
+
+A custom ActionMailer delivery method that sends emails via Microsoft Graph API using OAuth 2.0 client credentials flow.
+
+## Features
+
+- 🚀 Send emails through Microsoft Graph API (v1.0)
+- 🔐 OAuth 2.0 authentication with client credentials flow
+- 📎 Support for attachments
+- 📧 Support for HTML and plain text emails
+- 📬 Support for CC, BCC, and Reply-To recipients
+- 🔍 Comprehensive error handling and logging
+- ⚙️ Configurable SSL verification
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ms-graph-mailer', git: 'https://github.com/zauberware/ms-graph-mailer'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+### Azure AD App Setup
+
+1. Register an application in Azure Active Directory
+2. Grant the application `Mail.Send` API permission (Application permission, not delegated)
+3. Generate a client secret
+4. Note down:
+   - Tenant ID
+   - Client ID (Application ID)
+   - Client Secret
+
+### Rails Configuration
+
+Create an initializer file `config/initializers/ms_graph_mailer.rb`:
+
+```ruby
+MsGraphMailer.configure do |config|
+  config.tenant_id = ENV['AZURE_MAIL_APP_TENANT_ID']
+  config.client_id = ENV['AZURE_MAIL_APP_CLIENT_ID']
+  config.client_secret = ENV['AZURE_MAIL_APP_CLIENT_SECRET']
+  config.logger = Rails.logger
+end
+```
+
+Configure ActionMailer to use the Microsoft Graph delivery method:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :microsoft_graph
+config.action_mailer.microsoft_graph_settings = {
+  ssl_verify: true # Set to false to disable SSL verification (not recommended for production)
+}
+```
+
+### Environment Variables
+
+Set the following environment variables:
+
+```bash
+AZURE_MAIL_APP_TENANT_ID=your-tenant-id
+AZURE_MAIL_APP_CLIENT_ID=your-client-id
+AZURE_MAIL_APP_CLIENT_SECRET=your-client-secret
+```
+
+## Usage
+
+Once configured, the gem works automatically with ActionMailer. Just send emails as you normally would:
+
+```ruby
+require 'ms/graph/mailer'
+
+class UserMailer < ApplicationMailer
+  def welcome_email(user)
+    mail(
+      to: user.email,
+      subject: 'Welcome to Our App',
+      from: 'noreply@example.com'
+    )
+  end
+end
+
+# Send the email
+UserMailer.welcome_email(user).deliver_now
+```
+
+### Important Notes
+
+- The `from` email address must be a valid mailbox in your Microsoft 365 tenant
+- The Azure AD application must have the necessary permissions to send emails on behalf of the sender
+- Emails are sent using the `/users/{sender}/sendMail` endpoint
+
+## Error Handling
+
+The gem raises specific exceptions for different error scenarios:
+
+- `MsGraphMailer::ConfigurationError` - Invalid or missing configuration
+- `MsGraphMailer::AuthenticationError` - OAuth authentication failures
+- `MsGraphMailer::DeliveryError` - Email delivery failures
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zauberware/ms-graph-mailer.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Developed by [Zauberware Technologies GmbH](https://zauberware.com)

data/lib/ms/graph/mailer/delivery_method.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module MsGraphMailer
+  class DeliveryMethod
+    include Dry::Monads[:result]
+
+    attr_reader :settings
+
+    # INFO: settings is passed from config.action_mailer.<environment>
+    def initialize(settings)
+      @settings = settings
+      validate_configuration!
+    end
+
+    def deliver!(mail)
+      sender_email = extract_sender_email(mail)
+      raise DeliveryError, 'No sender email (From) specified in the email.' if sender_email.blank?
+
+      token_result = TokenService.new.call
+
+      if token_result.failure?
+        logger.error("Failed to get Graph token: #{token_result.failure}")
+        raise AuthenticationError, "Unable to authenticate with Microsoft Graph: #{token_result.failure}"
+      end
+
+      message_payload = {
+        message: build_message_payload(mail, sender_email),
+        saveToSentItems: true
+      }
+
+      response = connection(token_result.value!).post("users/#{CGI.escape(sender_email)}/sendMail") do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.body = message_payload.to_json
+      end
+
+      unless response.status == 202
+        error_body = begin
+          JSON.parse(response.body)
+        rescue StandardError
+          {}
+        end
+        error_msg = error_body.dig('error', 'message') || 'Unknown error'
+        logger.error("[MsGraphMailer] sendMail failed: [status: #{response.status}] - [body: #{response.body}]")
+        raise DeliveryError, "Microsoft Graph sendEmail failed with status #{response.status}: #{error_msg}"
+      end
+
+      logger.info('[MsGraphMailer] Email sent successfully via Microsoft Graph')
+      response
+    rescue Faraday::Error => e
+      logger.error("[MsGraphMailer] Network error: #{e.message}")
+      raise DeliveryError, "Network error sending email: #{e.message}"
+    end
+
+    private
+
+    def validate_configuration!
+      config = MsGraphMailer.configuration
+      return if config&.valid?
+
+      raise ConfigurationError,
+            'MsGraphMailer is not properly configured. Please configure tenant_id, client_id, and client_secret.'
+    end
+
+    def extract_sender_email(mail)
+      Array(mail.from).first.to_s.strip
+    end
+
+    def build_message_payload(mail, sender_email)
+      {
+        subject: mail.subject.to_s,
+        body: build_body(mail),
+        from: {
+          emailAddress: { address: sender_email }
+        },
+        toRecipients: build_recipients(mail.to),
+        ccRecipients: build_recipients(mail.cc),
+        bccRecipients: build_recipients(mail.bcc),
+        replyTo: build_recipients(mail.reply_to),
+        attachments: build_attachments(mail)
+      }.tap do |msg|
+        %i[toRecipients ccRecipients bccRecipients replyTo attachments].each do |field|
+          msg.delete(field) if msg[field].blank?
+        end
+      end
+    end
+
+    def build_body(mail)
+      if mail.multipart?
+        html_part = mail.html_part
+        text_part = mail.text_part
+
+        if html_part
+          {
+            contentType: 'HTML',
+            content: html_part.body.decoded
+          }
+        elsif text_part
+          {
+            contentType: 'Text',
+            content: text_part.body.decoded
+          }
+        else
+          {
+            contentType: 'Text',
+            content: ''
+          }
+        end
+      else
+        {
+          contentType: mail.content_type&.start_with?('text/html') ? 'HTML' : 'Text',
+          content: mail.body.decoded
+        }
+      end
+    end
+
+    def build_recipients(addresses)
+      Array(addresses).reject(&:blank?).map do |address|
+        { emailAddress: { address: address.to_s.strip } }
+      end
+    end
+
+    def build_attachments(mail)
+      mail.attachments.map do |attachment|
+        {
+          '@odata.type': '#microsoft.graph.fileAttachment',
+          name: attachment.filename.to_s,
+          contentType: attachment.mime_type.to_s,
+          contentBytes: Base64.strict_encode64(attachment.body.decoded)
+        }
+      end
+    end
+
+    def connection(access_token)
+      @connection ||= Faraday.new(url: 'https://graph.microsoft.com/v1.0/') do |f|
+        f.headers['Authorization'] = "Bearer #{access_token}"
+        f.adapter Faraday.default_adapter
+        # SSL verification configuration
+        f.ssl.verify = ssl_verify?
+      end
+    end
+
+    def ssl_verify?
+      # Allow disabling SSL verification via settings
+      settings[:ssl_verify].nil? || settings[:ssl_verify]
+    end
+
+    def logger
+      MsGraphMailer.configuration&.logger || Logger.new($stdout)
+    end
+  end
+end

data/lib/ms/graph/mailer/token_service.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module MsGraphMailer
+  class TokenService
+    include Dry::Monads[:result]
+
+    def call
+      fetch_token
+    end
+
+    private
+
+    def cached_token
+      logger.info('Checking for cached Microsoft Graph token...')
+      token = Rails.cache.read('microsoft_graph_token')
+      if token.present?
+        logger.info('Found valid cached Microsoft Graph token.')
+      else
+        logger.info('No valid cached Microsoft Graph token found.')
+      end
+      token
+    end
+
+    def fetch_token
+      validate_configuration!
+      token = cached_token
+      return Success(token) if token.present?
+
+      scope = 'https://graph.microsoft.com/.default'
+
+      logger.info("Attempting to fetch Microsoft Graph token for tenant: #{config.tenant_id}...")
+
+      response = connection.post("#{config.tenant_id}/oauth2/v2.0/token") do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+        req.body = {
+          client_id: config.client_id,
+          client_secret: config.client_secret,
+          grant_type: 'client_credentials',
+          scope: scope
+        }
+      end
+
+      logger.info("Graph token response status: #{response.status}")
+
+      body = JSON.parse(response.body)
+
+      if response.success? && body['access_token'].present?
+        access_token = body['access_token']
+        expires_in = body['expires_in'] || 3600 # Default to 1 hour
+        Rails.cache.write('microsoft_graph_token', access_token, expires_in: expires_in - 300)
+
+        logger.info("Successfully obtained and cached Graph token (expires in #{expires_in}s)")
+        Success(access_token)
+      else
+        error_msg = body['error_description'] || body['error'] || 'Unknown error'
+        logger.error("Failed to fetch Graph token - Status: #{response.status}, Error: #{error_msg}")
+        logger.error("Full response body: #{body}")
+        Failure("Failed to fetch Graph token: #{error_msg}")
+      end
+    rescue JSON::ParserError => e
+      logger.error("JSON parse error for Graph token response: #{e.message}")
+      logger.error("Response body: #{response&.body}")
+      Failure("Invalid response format: #{e.message}")
+    rescue Faraday::Error => e
+      logger.error("Faraday error fetching Graph token: #{e.message}")
+      Failure("Network error fetching Graph token: #{e.message}")
+    rescue StandardError => e
+      logger.error("Unexpected error fetching Graph token: #{e.message}")
+      Failure("Unexpected error: #{e.message}")
+    end
+
+    def validate_configuration!
+      return if config&.valid?
+
+      raise ConfigurationError,
+            'MsGraphMailer is not properly configured. Please configure tenant_id, client_id, and client_secret.'
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: 'https://login.microsoftonline.com') do |f|
+        f.request :url_encoded
+        f.adapter Faraday.default_adapter
+        f.ssl.verify = ssl_verify?
+      end
+    end
+
+    def ssl_verify?
+      # Default to true in production environments
+      return false if defined?(Rails) && Rails.env.development?
+
+      true
+    end
+
+    def config
+      MsGraphMailer.configuration
+    end
+
+    def logger
+      config&.logger || Logger.new($stdout)
+    end
+  end
+end

data/lib/ms/graph/mailer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MsGraphMailer
+  VERSION = '0.1.0'
+end

data/lib/ms/graph/mailer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'action_mailer'
+require 'faraday'
+require 'dry/monads'
+require 'json'
+require 'base64'
+require 'cgi'
+
+require_relative 'mailer/version'
+require_relative 'mailer/token_service'
+require_relative 'mailer/delivery_method'
+
+module MsGraphMailer
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class DeliveryError < Error; end
+  class ConfigurationError < Error; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+  end
+
+  class Configuration
+    attr_accessor :tenant_id, :client_id, :client_secret, :logger
+
+    def initialize
+      @tenant_id = nil
+      @client_id = nil
+      @client_secret = nil
+      @logger = nil
+    end
+
+    def valid?
+      tenant_id.present? && client_id.present? && client_secret.present?
+    end
+  end
+end
+
+# Register the delivery method with ActionMailer
+ActionMailer::Base.add_delivery_method(
+  :microsoft_graph,
+  MsGraphMailer::DeliveryMethod
+)

metadata

@@ -0,0 +1,208 @@
+--- !ruby/object:Gem::Specification
+name: ms-graph-mailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zauberware Technologies GmbH
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.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'
+- !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: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.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'
+description: A custom delivery method for ActionMailer that sends emails via Microsoft
+  Graph API using OAuth 2.0 client credentials flow
+email:
+- tech@zauberware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ms/graph/mailer.rb
+- lib/ms/graph/mailer/delivery_method.rb
+- lib/ms/graph/mailer/token_service.rb
+- lib/ms/graph/mailer/version.rb
+homepage: https://github.com/zauberware/ms-graph-mailer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zauberware/ms-graph-mailer
+  source_code_uri: https://github.com/zauberware/ms-graph-mailer
+  changelog_uri: https://github.com/zauberware/ms-graph-mailer/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: ActionMailer delivery method for Microsoft Graph API
+test_files: []