ms-graph-mailer 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a5f17bc2451562927b00da39c699228579048d89cf34966b399d78c4b3b24b
-  data.tar.gz: 3d5bb273afdd1861a226a42944586dfac77c4ea2591879fa0fdf24edb11f2b51
+  metadata.gz: bc38df909076fbf11baa641699ca2e813f683ab2dc95dc6c69c27b897bc85cd3
+  data.tar.gz: f48660fa9212b12343c92ef9a8786965fa8dfc3b86705c7c46cf86e339991557
 SHA512:
-  metadata.gz: c9e4732a3646a088d83974f85f48403be2ea34c5c48d0d14626ac6b6e371dd860e91577692940c40cba0ed70641556c224f0acce11c92b761d0b721a76afa902
-  data.tar.gz: 3135ace13bea41f6f31dae45dbbc8bfcec1870be5b47ff62995c81fe8340427d55ce10c5610f302d5d1b5c978d3f5fb85d3ee906756e76b5eb6bebf0252c158f
+  metadata.gz: '09014fecd0b2d3a1d5fdd417c887acdd9b6580cccf5a8e19c38ee92e9a44634785ccb2cab4865e96cb2814c61da89bc9ba6bbe9826cde8b30bbd452a25154743'
+  data.tar.gz: 6ea5c55727621b5fad871add5d91dc18ec55fa31648718a33531227cfcac7162b3fa20cd14a46a2038d3d5e2cb7e614ebc95cf5670680d9baf8ab55c4d058855

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [1.1.1] - 2026-11-06
+
+### Fixed
+
+- `In-Reply-To` and `References` headers are no longer dropped when sending.
+  The JSON `sendMail` payload cannot carry standard internet message headers,
+  so they are now mapped to their MAPI extended properties
+  (`PidTagInReplyToId` / `PidTagInternetReferences`), keeping replies threaded
+  in the recipient's mail client.
+
+## [1.1.0] - 2026-11-06
+
+### Added
+
+- `MsGraphMailer::DeliveryError` exposes `status`, `code`, `retry_after`, `request_id` and
+  `client_request_id`, plus `throttled?` (429/503 — rejected, safe to retry) and
+  `outcome_unknown?` (other 5xx and network errors — the mail may have been sent).
+- Every sendMail request carries a generated `client-request-id`; request ids and
+  `Retry-After` are logged on success and failure.
+- `open_timeout` / `timeout` configuration options for the sendMail request.
+
+### Changed
+
+- Error classes moved to `lib/ms/graph/mailer/errors.rb`. Error messages are unchanged.
+
 ## [1.0.0] - 2025-12-15
 
 ### Added
@@ -43,5 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configuration system for tenant, client credentials
 - Integration with Rails logger
 
+[1.1.1]: https://github.com/zauberware/ms-graph-mailer/releases/tag/v1.1.1
+[1.1.0]: https://github.com/zauberware/ms-graph-mailer/releases/tag/v1.1.0
 [1.0.0]: https://github.com/zauberware/ms-graph-mailer/releases/tag/v1.0.0
 [0.1.0]: https://github.com/zauberware/ms-graph-mailer/releases/tag/v0.1.0

data/README.md

@@ -48,6 +48,9 @@ MsGraphMailer.configure do |config|
   config.client_id = ENV['AZURE_MAIL_APP_CLIENT_ID']
   config.client_secret = ENV['AZURE_MAIL_APP_CLIENT_SECRET']
   config.logger = Rails.logger
+  # Optional: request timeouts in seconds (default: HTTP adapter defaults)
+  config.open_timeout = 10
+  config.timeout = 120
 end
 ```
 
@@ -106,6 +109,21 @@ The gem raises specific exceptions for different error scenarios:
 - `MsGraphMailer::AuthenticationError` - OAuth authentication failures
 - `MsGraphMailer::DeliveryError` - Email delivery failures
 
+`DeliveryError` carries the Graph response details so callers can decide whether to retry:
+
+```ruby
+rescue MsGraphMailer::DeliveryError => e
+  e.status            # => 503
+  e.code              # => "CommandConcurrencyLimitReached"
+  e.retry_after       # => 7 (seconds, from the Retry-After header; nil if absent)
+  e.request_id        # => Graph request-id, for Microsoft support
+  e.client_request_id # => id the gem sent with the request (also set on timeouts)
+
+  e.throttled?        # 429/503: Graph rejected the request, nothing was sent - safe to retry
+  e.outcome_unknown?  # other 5xx or network error/timeout - the mail may have been sent
+end
+```
+
 ## Development
 
 After checking out the repo, run:

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

@@ -4,6 +4,10 @@ module MsGraphMailer
   class DeliveryMethod
     include Dry::Monads[:result]
 
+    # PidTagInReplyToId (0x1042) / PidTagInternetReferences (0x1039)
+    IN_REPLY_TO_PROPERTY_ID = 'String 0x1042'
+    REFERENCES_PROPERTY_ID = 'String 0x1039'
+
     attr_reader :settings
 
     # INFO: settings is passed from config.action_mailer.<environment>
@@ -28,31 +32,56 @@ module MsGraphMailer
         saveToSentItems: true
       }
 
+      # Sent with the request and echoed back by Graph, so a failure can be
+      # traced with Microsoft even when no response arrives (timeouts).
+      client_request_id = SecureRandom.uuid
+
       response = connection(token_result.value!).post("users/#{CGI.escape(sender_email)}/sendMail") do |req|
         req.headers['Content-Type'] = 'application/json'
+        req.headers['client-request-id'] = client_request_id
+        req.headers['return-client-request-id'] = 'true'
         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
+      raise build_delivery_error(response, client_request_id) unless response.status == 202
 
-      logger.info('[MsGraphMailer] Email sent successfully via Microsoft Graph')
+      logger.info('[MsGraphMailer] Email sent successfully via Microsoft Graph ' \
+                  "[request-id: #{response.headers['request-id']}] [client-request-id: #{client_request_id}]")
       response
     rescue Faraday::Error => e
-      logger.error("[MsGraphMailer] Network error: #{e.message}")
-      raise DeliveryError, "Network error sending email: #{e.message}"
+      logger.error("[MsGraphMailer] Network error: #{e.message} [client-request-id: #{client_request_id}]")
+      raise DeliveryError.new("Network error sending email: #{e.message}",
+                              client_request_id: client_request_id, network_error: true)
     end
 
     private
 
+    def build_delivery_error(response, client_request_id)
+      error = parse_error_body(response.body)
+      request_id = response.headers['request-id']
+      retry_after = DeliveryError.parse_retry_after(response.headers['Retry-After'])
+
+      logger.error("[MsGraphMailer] sendMail failed: [status: #{response.status}] [code: #{error['code']}] " \
+                   "[request-id: #{request_id}] [client-request-id: #{client_request_id}] " \
+                   "[retry-after: #{retry_after.inspect}] - [body: #{response.body}]")
+
+      DeliveryError.new(
+        "Microsoft Graph sendEmail failed with status #{response.status}: #{error['message'] || 'Unknown error'}",
+        status: response.status,
+        code: error['code'],
+        retry_after: retry_after,
+        request_id: request_id,
+        client_request_id: client_request_id
+      )
+    end
+
+    def parse_error_body(body)
+      parsed = JSON.parse(body.to_s)
+      parsed.is_a?(Hash) && parsed['error'].is_a?(Hash) ? parsed['error'] : {}
+    rescue JSON::ParserError
+      {}
+    end
+
     def validate_configuration!
       config = MsGraphMailer.configuration
       return if config&.valid?
@@ -76,14 +105,42 @@ module MsGraphMailer
         ccRecipients: build_recipients(mail.cc),
         bccRecipients: build_recipients(mail.bcc),
         replyTo: build_recipients(mail.reply_to),
-        attachments: build_attachments(mail)
+        attachments: build_attachments(mail),
+        singleValueExtendedProperties: build_threading_properties(mail)
       }.tap do |msg|
-        %i[toRecipients ccRecipients bccRecipients replyTo attachments].each do |field|
+        %i[toRecipients ccRecipients bccRecipients replyTo attachments singleValueExtendedProperties].each do |field|
           msg.delete(field) if msg[field].blank?
         end
       end
     end
 
+    # Graph's sendMail only accepts x-* custom headers via
+    # internetMessageHeaders, so the standard threading headers
+    # (In-Reply-To/References) would silently get lost. Mapping them to their
+    # MAPI extended properties makes Exchange emit them on the wire, keeping
+    # replies threaded in the recipient's client.
+    def build_threading_properties(mail)
+      properties = []
+
+      in_reply_to = format_message_ids(mail.in_reply_to)
+      references = format_message_ids(mail.references)
+
+      properties << { id: IN_REPLY_TO_PROPERTY_ID, value: in_reply_to } if in_reply_to
+      properties << { id: REFERENCES_PROPERTY_ID, value: references } if references
+      properties
+    end
+
+    # The mail gem parses message-id fields to bare ids (no angle brackets);
+    # the RFC 5322 header format Exchange writes needs them re-added.
+    def format_message_ids(ids)
+      formatted = Array(ids).compact.map(&:to_s).reject(&:empty?).map do |id|
+        id.start_with?('<') ? id : "<#{id}>"
+      end
+      return nil if formatted.empty?
+
+      formatted.join(' ')
+    end
+
     def build_body(mail)
       if mail.multipart?
         html_part = mail.html_part
@@ -133,6 +190,8 @@ module MsGraphMailer
     def connection(access_token)
       @connection ||= Faraday.new(url: 'https://graph.microsoft.com/v1.0/') do |f|
         f.headers['Authorization'] = "Bearer #{access_token}"
+        f.options.open_timeout = MsGraphMailer.configuration&.open_timeout
+        f.options.timeout = MsGraphMailer.configuration&.timeout
         f.adapter Faraday.default_adapter
         # SSL verification configuration
         f.ssl.verify = ssl_verify?

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module MsGraphMailer
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class ConfigurationError < Error; end
+
+  # Raised when Microsoft Graph does not accept a sendMail request.
+  #
+  # Besides the message (kept stable for callers that persist or match it),
+  # the error exposes the response details a caller needs to decide whether a
+  # retry is safe:
+  #
+  # - throttled?        Graph rejected the request (429, or 503 such as
+  #                     "CommandConcurrencyLimitReached"). Nothing was sent;
+  #                     retry after #retry_after seconds.
+  # - outcome_unknown?  Gateway errors and network failures/timeouts. The
+  #                     mail may or may not have been sent — retrying blindly
+  #                     risks a duplicate.
+  class DeliveryError < Error
+    THROTTLED_STATUSES = [429, 503].freeze
+
+    attr_reader :status, :code, :retry_after, :request_id, :client_request_id
+
+    def initialize(message = nil, status: nil, code: nil, retry_after: nil, request_id: nil, # rubocop:disable Metrics/ParameterLists
+                   client_request_id: nil, network_error: false)
+      super(message)
+      @status = status
+      @code = code
+      @retry_after = retry_after
+      @request_id = request_id
+      @client_request_id = client_request_id
+      @network_error = network_error
+    end
+
+    def throttled?
+      THROTTLED_STATUSES.include?(status)
+    end
+
+    def outcome_unknown?
+      return true if @network_error
+      return false if status.nil? || throttled?
+
+      status >= 500
+    end
+
+    # Retry-After is either delta-seconds or an HTTP date (RFC 9110 §10.2.3).
+    # Returns whole seconds, or nil when the header is absent or unparsable.
+    def self.parse_retry_after(value, now: Time.now)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      raw = value.to_s.strip
+      return raw.to_i if raw.match?(/\A\d+\z/)
+
+      [(Time.httpdate(raw) - now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+end

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

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

data/lib/ms/graph/mailer.rb

@@ -6,17 +6,14 @@ require 'dry/monads'
 require 'json'
 require 'base64'
 require 'cgi'
+require 'securerandom'
 
 require_relative 'mailer/version'
+require_relative 'mailer/errors'
 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
 
@@ -27,13 +24,17 @@ module MsGraphMailer
   end
 
   class Configuration
-    attr_accessor :tenant_id, :client_id, :client_secret, :logger
+    # open_timeout / timeout (seconds) apply to the sendMail request. nil keeps
+    # the HTTP adapter's defaults.
+    attr_accessor :tenant_id, :client_id, :client_secret, :logger, :open_timeout, :timeout
 
     def initialize
       @tenant_id = nil
       @client_id = nil
       @client_secret = nil
       @logger = nil
+      @open_timeout = nil
+      @timeout = nil
     end
 
     def valid?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ms-graph-mailer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Zauberware Technologies GmbH
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-15 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -80,104 +80,90 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.3'
-- !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'
+        version: '13.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '13.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.92'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.92'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.10'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.34'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.34'
 description: A custom delivery method for ActionMailer that sends emails via Microsoft
   Graph API using OAuth 2.0 client credentials flow
 email:
@@ -191,6 +177,7 @@ files:
 - README.md
 - lib/ms/graph/mailer.rb
 - lib/ms/graph/mailer/delivery_method.rb
+- lib/ms/graph/mailer/errors.rb
 - lib/ms/graph/mailer/token_service.rb
 - lib/ms/graph/mailer/version.rb
 homepage: https://github.com/zauberware/ms-graph-mailer