azure_communication_email 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13809a220b8a5a263414d0b53618afb1ed9006d576d9df3bc784b766e3c6faf
-  data.tar.gz: 1cf7750c4545e6dfe01c756a950212387e771a080345532b9cdf368bed4fe548
+  metadata.gz: 7dc5641d67751daefdc4edd8e5f749235c3432fab68daa16dc5050b6d0f574d4
+  data.tar.gz: 9994f7260ac36ce4a284d0113b344f3b8a71b4cb41185b7da60f479a302d18f1
 SHA512:
-  metadata.gz: cda943ef50229a34293a1c0b87fc9b99835c6279c863a5f4857dc6adbbb2c88bec93596751e59cdb55c17ca25949c223cb27c551ce1e96d7c02976928f029761
-  data.tar.gz: ee436d8da33038971b9491568a2794420b448662a5086f5a4164fca2ca80fdb2bd10ddff6979e0e96362f64e3ad7f8e9454e1e1147fc3574dac0dc45b562d64f
+  metadata.gz: 5da5ad3a1cf4b559c320e3405c4d691a357e3db8fbb918aae7b6524f3b04f7b0ab97d90fa9741888d063964490293d0ebdb92f788bcc5090266f9de87394a674
+  data.tar.gz: 1de7203d9fe1bec1eb197f7bf47bc2ee31911be9f1edd7de57f51729290bb4a4327134bf9ca94fe377672e4a61d28059970c16f546a25a39da5447d42f00bcfa

data/README.md

@@ -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,13 +26,21 @@ 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"), # e.g., "https://<RESOURCE_NAME>.communication.azure.com"
-    access_key: ENV.fetch("ACS_EMAIL_ACCESS_KEY"),
+    endpoint: ENV.fetch("ACS_EMAIL_ENDPOINT"),
+    access_key: ENV.fetch("ACS_EMAIL_ACCESS_KEY")
   }
 end
 ```
 
-Then, you can use Action Mailer as usual:
+`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
@@ -43,9 +51,34 @@ class UserMailer < ApplicationMailer
 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

data/lib/azure_communication_email/delivery_method.rb

@@ -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

@@ -122,11 +122,13 @@ module AzureCommunicationEmail
       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
 

data/lib/azure_communication_email/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AzureCommunicationEmail
-  VERSION = "0.2.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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Devran Cosmo Uenal
@@ -95,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 Email Communications Service Delivery Method for Action Mailer
 test_files: []