azure_communication_email 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6425a9b60979a7f4d2388fd367a092ee2f63ffa90c087ab71e923bb8944419f
-  data.tar.gz: a455a2ec63a22d96849d102a0af4860633c76720ce85d6b35d20b9fa68461c96
+  metadata.gz: 7dc5641d67751daefdc4edd8e5f749235c3432fab68daa16dc5050b6d0f574d4
+  data.tar.gz: 9994f7260ac36ce4a284d0113b344f3b8a71b4cb41185b7da60f479a302d18f1
 SHA512:
-  metadata.gz: df8bb2c7678d15227d6b50d3ecc950cf8984a05ef71f870e82dd0fc8f6bce24439fd59d291a684d280e3a61e8f987579675a9d939bf6a49deda8971e4774880b
-  data.tar.gz: 7ca782265ac31312825f7fbc78cac03225266e9edfb55cd8e9ca6d62012f780a2462d2c254e91c3748fb4dd10bebe1fc74935a5c88a1d271f97c1e6e1f93ca65
+  metadata.gz: 5da5ad3a1cf4b559c320e3405c4d691a357e3db8fbb918aae7b6524f3b04f7b0ab97d90fa9741888d063964490293d0ebdb92f788bcc5090266f9de87394a674
+  data.tar.gz: 1de7203d9fe1bec1eb197f7bf47bc2ee31911be9f1edd7de57f51729290bb4a4327134bf9ca94fe377672e4a61d28059970c16f546a25a39da5447d42f00bcfa

data/README.md

@@ -1,6 +1,6 @@
 # Azure Communication Email
 
-Azure Communication Email is an Action Mailer delivery method for Ruby on Rails using the Azure Communication Email API.
+Azure Communication Email is an Action Mailer delivery method for Ruby on Rails using the [Azure Email Communications Service](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/email/create-email-communication-resource?pivots=platform-azp).
 
 ## Installation
 
@@ -16,9 +16,9 @@ Or add it manually to your Gemfile:
 gem "azure_communication_email"
 ```
 
-## Usage
+## Configuration
 
-To send emails using Azure Communication Services, configure Action Mailer with the `:azure_communication_email` delivery method and provide the necessary credentials.
+Create an Azure Communication Services resource, connect a verified email domain, and configure the delivery method in the environment where email should be sent:
 
 ```ruby
 # config/environments/production.rb
@@ -26,12 +26,61 @@ To send emails using Azure Communication Services, configure Action Mailer with
 Rails.application.configure do
   config.action_mailer.delivery_method = :azure_communication_email
   config.action_mailer.azure_communication_email_settings = {
-    endpoint:   ENV.fetch("ACS_EMAIL_ENDPOINT"),
-    access_key: ENV.fetch("ACS_EMAIL_ACCESS_KEY"),
+    endpoint: ENV.fetch("ACS_EMAIL_ENDPOINT"),
+    access_key: ENV.fetch("ACS_EMAIL_ACCESS_KEY")
   }
 end
 ```
 
+`endpoint` is the complete Communication Services endpoint, for example `https://my-resource.communication.azure.com`. `access_key` is one of that resource's access keys.
+
+The optional `api_version` setting defaults to `2025-01-15-preview`. This version is used because it supports sender display names for custom domains.
+
+Keep `config.action_mailer.delivery_method = :test` in the test environment so tests do not send real email.
+
+## Usage
+
+Use Action Mailer normally; no Azure-specific mailer class is needed:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email(user)
+    @user = user
+    mail(to: @user.email, from: "donotreply@<yourdomain>.com", subject: "Hello World!")
+  end
+end
+```
+
+Send through Active Job in most application code:
+
+```ruby
+UserMailer.with(user: user).welcome_email.deliver_later
+```
+
+The delivery method maps Action Mailer messages to Azure, including:
+
+- plain-text and HTML bodies, including multipart messages
+- `to`, `cc`, `bcc`, and `reply_to` recipients with display names
+- regular and inline attachments
+- `X-` custom headers
+- a sender display name when using a custom domain
+
+Azure limits the total request size, including attachments, to 10 MB.
+
+## Delivery status and errors
+
+Azure accepts email asynchronously. A successful `deliver_now` or delivery job means Azure returned `202 Accepted`; it does not guarantee final delivery to the recipient. Use Azure Monitor or Event Grid email events for final delivery and bounce tracking.
+
+Configuration errors, connection failures, timeouts, authentication failures, and non-successful HTTP responses raise `AzureCommunicationEmail::Error`. The HTTP connection timeout is 5 seconds and the response timeout is 15 seconds.
+
+For a quick production check, send a message from the Rails console with `deliver_now`. Use a verified sender address and inspect Azure's email logs if the recipient does not receive it.
+
+## Links
+
+- [Service limits for Azure Communication Services](https://learn.microsoft.com/en-us/azure/communication-services/concepts/service-limits#email)
+- [Monitor Azure Communication Services email events](https://learn.microsoft.com/en-us/azure/communication-services/concepts/email/email-event-data)
+- [How to add and remove Multiple Sender Addresses to Email Communication Service](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/email/add-multiple-senders?pivots=platform-azp)
+
 ## Contributing
 
 Bug reports and pull requests are welcome.

data/lib/azure_communication_email/delivery_method.rb

@@ -10,7 +10,7 @@ require "uri"
 
 module AzureCommunicationEmail
   class DeliveryMethod
-    DEFAULTS = { api_version: "2023-03-31" }
+    DEFAULTS = { api_version: "2025-01-15-preview" }
 
     attr_accessor :endpoint, :api_version, :access_key
 
@@ -53,6 +53,8 @@ module AzureCommunicationEmail
       end
 
       response
+    rescue Error
+      raise
     rescue StandardError => e
       raise Error, "Error sending email: #{e.message}"
     end

data/lib/azure_communication_email/payload.rb

@@ -12,32 +12,44 @@ module AzureCommunicationEmail
 
     def as_json
       hash = {
-        "senderAddress" => first_address(@mail.from),
+        "senderAddress" => first_sender_address,
         "content" => {
           "subject"   => @mail.subject.to_s,
           "plainText" => plain_text_body
         },
         "recipients" => {
-          "to" => recipient_objects(@mail.to)
+          "to" => recipient_objects(:to)
         }
       }
 
-      html = html_body
-      hash["content"]["html"] = html if html.present?
+      # Does only work with custom domains
+      if (name = first_sender_display_name).present?
+        hash["senderDisplayName"] = name
+      end
+
+      if (html = html_body).present?
+        hash["content"]["html"] = html
+      end
 
-      cc  = recipient_objects(@mail.cc)
-      bcc = recipient_objects(@mail.bcc)
-      hash["recipients"]["cc"]  = cc  if cc.present?
-      hash["recipients"]["bcc"] = bcc if bcc.present?
+      if (cc = recipient_objects(:cc)).present?
+        hash["recipients"]["cc"] = cc
+      end
 
-      reply_to = recipient_objects(@mail.reply_to)
-      hash["replyTo"] = reply_to if reply_to.present?
+      if (bcc = recipient_objects(:bcc)).present?
+        hash["recipients"]["bcc"] = bcc
+      end
+
+      if (reply_to = recipient_objects(:reply_to)).present?
+        hash["replyTo"] = reply_to
+      end
 
-      headers = custom_headers
-      hash["headers"] = headers if headers.present?
+      if (headers = custom_headers).present?
+        hash["headers"] = headers
+      end
 
-      attachments = attachment_objects
-      hash["attachments"] = attachments if attachments.present?
+      if (attachments = attachment_objects).present?
+        hash["attachments"] = attachments
+      end
 
       hash
     end
@@ -49,34 +61,74 @@ module AzureCommunicationEmail
     private
 
     def plain_text_body
-      if @mail.text_part
-        @mail.text_part.decoded
-      else
-        @mail.body.decoded.to_s
-      end
+      return extract_text_part if @mail.text_part
+      return extract_plain_body if @mail.mime_type.to_s.start_with?("text/plain")
+      return extract_bare_body   if @mail.mime_type.to_s.blank?
+
+      "" # HTML-only message
     end
 
     def html_body
-      @mail.html_part&.decoded
+      return extract_html_part if @mail.html_part
+      return extract_html_body if @mail.mime_type.to_s.start_with?("text/html")
+
+      nil
+    end
+
+    def extract_text_part
+      @mail.text_part.body.decoded.to_s
     end
 
-    def first_address(list)
-      Array(list).compact_blank.first
+    def extract_plain_body
+      @mail.body.decoded.to_s
     end
 
-    def recipient_objects(addresses)
-      Array(addresses).compact_blank.map { |address| { "address" => address } }
+    def extract_bare_body
+      @mail.body&.decoded.to_s
+    end
+
+    def extract_html_part
+      @mail.html_part.body.decoded.to_s
+    end
+
+    def extract_html_body
+      @mail.body.decoded.to_s
+    end
+
+    def address_list(field_sym)
+      field = @mail[field_sym]
+      return [] unless field.respond_to?(:addrs)
+      field.addrs
+    end
+
+    def first_sender_address
+      address_list(:from).first&.address.to_s
+    end
+
+    def first_sender_display_name
+      address_list(:from).first&.display_name.to_s.strip
+    end
+
+    def recipient_objects(field_sym)
+      address_list(field_sym).map do |addr|
+        obj = { "address" => addr.address.to_s }
+        name = addr.display_name.to_s.strip
+        obj["displayName"] = name if name.present?
+        obj
+      end
     end
 
     def attachment_objects
       return [] unless @mail.attachments&.any?
 
       @mail.attachments.map do |attachment|
-        {
+        object = {
           "name" => attachment.filename.to_s,
           "contentType" => attachment.mime_type.to_s,
           "contentInBase64" => Base64.strict_encode64(attachment.body.decoded)
         }
+        object["contentId"] = attachment.cid if attachment.inline?
+        object
       end
     end
 
@@ -84,8 +136,8 @@ module AzureCommunicationEmail
       return {} unless @mail.header
 
       @mail.header.fields
-        .select { |field| field.name =~ /\AX-/i }
-        .to_h { |field| [ field.name, field.value.to_s ] }
+           .select { |field| field.name =~ /\AX-/i }
+           .to_h { |field| [ field.name, field.value.to_s ] }
     end
   end
 end

data/lib/azure_communication_email/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AzureCommunicationEmail
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/azure_communication_email.rb

@@ -3,7 +3,6 @@
 require_relative "azure_communication_email/version"
 require_relative "azure_communication_email/delivery_method"
 
-# Auto-register with Rails when loaded
-if defined?(Rails) && defined?(ActionMailer)
-  ActionMailer::Base.add_delivery_method :azure_communication_email, AzureCommunicationEmail::DeliveryMethod
+ActiveSupport.on_load(:action_mailer) do
+  add_delivery_method :azure_communication_email, AzureCommunicationEmail::DeliveryMethod
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: azure_communication_email
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Devran Cosmo Uenal
@@ -65,8 +65,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.8'
-description: Action Mailer delivery method using the Azure Communication Services
-  Email API.
+description: Action Mailer delivery method using the Azure Email Communications Service.
 email:
 - maccosmo@gmail.com
 executables: []
@@ -96,14 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.10
 specification_version: 4
-summary: Azure Communication Services Email Delivery Method for Action Mailer
+summary: Azure Email Communications Service Delivery Method for Action Mailer
 test_files: []