ms-graph-mailer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a5f17bc2451562927b00da39c699228579048d89cf34966b399d78c4b3b24b
-  data.tar.gz: 3d5bb273afdd1861a226a42944586dfac77c4ea2591879fa0fdf24edb11f2b51
+  metadata.gz: 469b5d7a57ff7c226a55b9e73cd2995ee229f9f22824e9155585d905c66b5887
+  data.tar.gz: 4a358f5c1ea87954bfa99169a41faa6f226d2fc80a054dede48ced754b32a6ac
 SHA512:
-  metadata.gz: c9e4732a3646a088d83974f85f48403be2ea34c5c48d0d14626ac6b6e371dd860e91577692940c40cba0ed70641556c224f0acce11c92b761d0b721a76afa902
-  data.tar.gz: 3135ace13bea41f6f31dae45dbbc8bfcec1870be5b47ff62995c81fe8340427d55ce10c5610f302d5d1b5c978d3f5fb85d3ee906756e76b5eb6bebf0252c158f
+  metadata.gz: fa851676f45ced636be7c356cf7f33dc36ecc2685d9fb6662692756b0fdcae2fbb908f30b5b9908c08a88192c2f1858e78b1bf23d982e6034b9e25b3373245c7
+  data.tar.gz: 2c9a35d08b4579a65bd9c1596d0074cf21368f596c0a5a18362d4136e40981a1e521ad89a88b6bf25f5a6e8059ae9e67149c9b72cccdffdabcd1be6e78afa9ed

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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 +58,6 @@ 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.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

@@ -28,31 +28,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?
@@ -133,6 +158,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.0'
 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.0
 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
@@ -191,6 +191,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