azure_communication_email 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6425a9b60979a7f4d2388fd367a092ee2f63ffa90c087ab71e923bb8944419f
+  data.tar.gz: a455a2ec63a22d96849d102a0af4860633c76720ce85d6b35d20b9fa68461c96
+SHA512:
+  metadata.gz: df8bb2c7678d15227d6b50d3ecc950cf8984a05ef71f870e82dd0fc8f6bce24439fd59d291a684d280e3a61e8f987579675a9d939bf6a49deda8971e4774880b
+  data.tar.gz: 7ca782265ac31312825f7fbc78cac03225266e9edfb55cd8e9ca6d62012f780a2462d2c254e91c3748fb4dd10bebe1fc74935a5c88a1d271f97c1e6e1f93ca65

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Devran Cosmo Uenal
+
+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,41 @@
+# Azure Communication Email
+
+Azure Communication Email is an Action Mailer delivery method for Ruby on Rails using the Azure Communication Email API.
+
+## Installation
+
+Install the gem and add to your application's Gemfile by executing:
+
+```bash
+bundle add azure_communication_email
+```
+
+Or add it manually to your Gemfile:
+
+```ruby
+gem "azure_communication_email"
+```
+
+## Usage
+
+To send emails using Azure Communication Services, configure Action Mailer with the `:azure_communication_email` delivery method and provide the necessary credentials.
+
+```ruby
+# config/environments/production.rb
+
+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"),
+  }
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/azure_communication_email/delivery_method.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "payload"
+require_relative "hmac_auth"
+require_relative "error"
+
+require "active_support/all"
+require "net/http"
+require "uri"
+
+module AzureCommunicationEmail
+  class DeliveryMethod
+    DEFAULTS = { api_version: "2023-03-31" }
+
+    attr_accessor :endpoint, :api_version, :access_key
+
+    def initialize(values)
+      @endpoint     = values.fetch(:endpoint)
+      @api_version  = values.fetch(:api_version, DEFAULTS[:api_version])
+      @access_key   = values.fetch(:access_key)
+    end
+
+    def deliver!(mail)
+      raise ArgumentError, "Missing :endpoint configuration (https://my-resource.communication.azure.com)" if @endpoint.blank?
+      raise ArgumentError, "Missing :access_key configuration" if @access_key.blank?
+
+      path_and_query = "/emails:send?api-version=#{@api_version}"
+      uri = URI.join(@endpoint, path_and_query)
+
+      # Prepare email payload
+      payload = Payload.new(mail)
+      body_json = payload.to_json
+
+      # Sign request
+      hmac_auth = HmacAuth.new(endpoint: @endpoint, access_key: @access_key)
+      headers = hmac_auth.sign_request(
+        http_method: "POST",
+        path_and_query: path_and_query,
+        body: body_json
+      )
+
+      # Azure Communication Services Email
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 5
+      http.read_timeout = 15
+      request = Net::HTTP::Post.new(uri.request_uri, headers)
+      request.body = body_json
+
+      response = http.request(request)
+      unless response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPAccepted)
+        raise Error, "Failed to send email: #{response.code} #{response.message} - #{response.body}"
+      end
+
+      response
+    rescue StandardError => e
+      raise Error, "Error sending email: #{e.message}"
+    end
+  end
+end

data/lib/azure_communication_email/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AzureCommunicationEmail
+  class Error < StandardError; end
+end

data/lib/azure_communication_email/hmac_auth.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "uri"
+require "openssl"
+require "base64"
+require "time"
+
+# HMAC authentication for Azure Communication Services Email REST API
+#
+# Reference:
+# https://learn.microsoft.com/en-us/azure/communication-services/tutorials/hmac-header-tutorial?pivots=programming-language-python
+
+module AzureCommunicationEmail
+  class HmacAuth
+    def initialize(endpoint:, access_key:)
+      @endpoint = endpoint # e.g. "https://my-resource.communication.azure.com"
+      @access_key = access_key
+    end
+
+    # body: must be the exact JSON string that will go in request.body
+    def sign_request(http_method:, path_and_query:, body:)
+      uri = URI.join(@endpoint, path_and_query)
+
+      content_bytes = body.encode("utf-8")
+
+      # RFC1123 UTC timestamp
+      date = Time.now.utc.httpdate
+
+      # Base64(SHA256(request-body-bytes))
+      content_hash = base64_sha256(content_bytes)
+
+      # StringToSign
+      host = uri.host.downcase
+      string_to_sign = [
+        http_method.upcase,
+        path_and_query,
+        "#{date};#{host};#{content_hash}"
+      ].join("\n")
+
+      signature = base64_hmac_sha256(string_to_sign, @access_key)
+
+      authorization_header = "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=#{signature}"
+
+      {
+        "x-ms-date" => date,
+        "x-ms-content-sha256" => content_hash,
+        "Authorization" => authorization_header,
+        "Content-Type" => "application/json"
+      }
+    end
+
+    private
+
+    def base64_sha256(bytes)
+      digest = OpenSSL::Digest::SHA256.digest(bytes)
+      Base64.strict_encode64(digest)
+    end
+
+    def base64_hmac_sha256(string_to_sign, base64_secret)
+      secret = Base64.decode64(base64_secret)
+      hmac   = OpenSSL::HMAC.digest("sha256", secret, string_to_sign.encode("utf-8"))
+      Base64.strict_encode64(hmac)
+    end
+  end
+end

data/lib/azure_communication_email/payload.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+require "json"
+require "base64"
+
+module AzureCommunicationEmail
+  class Payload
+    def initialize(mail)
+      @mail = mail
+    end
+
+    def as_json
+      hash = {
+        "senderAddress" => first_address(@mail.from),
+        "content" => {
+          "subject"   => @mail.subject.to_s,
+          "plainText" => plain_text_body
+        },
+        "recipients" => {
+          "to" => recipient_objects(@mail.to)
+        }
+      }
+
+      html = html_body
+      hash["content"]["html"] = html if html.present?
+
+      cc  = recipient_objects(@mail.cc)
+      bcc = recipient_objects(@mail.bcc)
+      hash["recipients"]["cc"]  = cc  if cc.present?
+      hash["recipients"]["bcc"] = bcc if bcc.present?
+
+      reply_to = recipient_objects(@mail.reply_to)
+      hash["replyTo"] = reply_to if reply_to.present?
+
+      headers = custom_headers
+      hash["headers"] = headers if headers.present?
+
+      attachments = attachment_objects
+      hash["attachments"] = attachments if attachments.present?
+
+      hash
+    end
+
+    def to_json(*args)
+      JSON.generate(as_json, *args)
+    end
+
+    private
+
+    def plain_text_body
+      if @mail.text_part
+        @mail.text_part.decoded
+      else
+        @mail.body.decoded.to_s
+      end
+    end
+
+    def html_body
+      @mail.html_part&.decoded
+    end
+
+    def first_address(list)
+      Array(list).compact_blank.first
+    end
+
+    def recipient_objects(addresses)
+      Array(addresses).compact_blank.map { |address| { "address" => address } }
+    end
+
+    def attachment_objects
+      return [] unless @mail.attachments&.any?
+
+      @mail.attachments.map do |attachment|
+        {
+          "name" => attachment.filename.to_s,
+          "contentType" => attachment.mime_type.to_s,
+          "contentInBase64" => Base64.strict_encode64(attachment.body.decoded)
+        }
+      end
+    end
+
+    def custom_headers
+      return {} unless @mail.header
+
+      @mail.header.fields
+        .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

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

data/lib/azure_communication_email.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+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
+end

data/sig/azure_communication_email.rbs

@@ -0,0 +1,4 @@
+module AzureCommunicationEmail
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: azure_communication_email
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Devran Cosmo Uenal
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: Action Mailer delivery method using the Azure Communication Services
+  Email API.
+email:
+- maccosmo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/azure_communication_email.rb
+- lib/azure_communication_email/delivery_method.rb
+- lib/azure_communication_email/error.rb
+- lib/azure_communication_email/hmac_auth.rb
+- lib/azure_communication_email/payload.rb
+- lib/azure_communication_email/version.rb
+- sig/azure_communication_email.rbs
+homepage: https://github.com/Cosmo/azure_communication_email
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Cosmo/azure_communication_email
+  source_code_uri: https://github.com/Cosmo/azure_communication_email
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Azure Communication Services Email Delivery Method for Action Mailer
+test_files: []