courrier 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555584763bab84eb75f07a5a7fa43fb4e4a65c3b1bb52de2c8e551c744fd0625
-  data.tar.gz: 4901dfab5c8c70d2f741e6c5edc0014e2aa7a9ca4afddc011d0d946464da709d
+  metadata.gz: d793cbc73ad9612cbb5e010e6aed85f9885e41fc8b672d16f82a6d155f63b726
+  data.tar.gz: 1143fc17abc330c3f94192ec95aea7618583266491f109b62aee3178826ede97
 SHA512:
-  metadata.gz: 93d5a592840d197493eafc3b8cac47b03218b9d8bdce88ef2e666685468a32879583ea7bb7adc1e84a665864ee5d4aebc80e982606f78836d2cf996e7fd5e602
-  data.tar.gz: d2e4391d1ea6d24031fbba9539f4935386b552184e145a4a2582e0a9a72003d3f79ed2afc6091ca9b2f4069b725e8a778602b8d31fe688999fad2badc4535276
+  metadata.gz: 64991e00fdb46c81164c29ffc7dc9de6078bcbc6cad12407355424f19f54e3a767e8732abf1438105d1f14b3ebe8ecf8367aa88bd7e53fadd7787fa8dd163609
+  data.tar.gz: eed7664f6a7211fc98e8cd53e0dc24ad1784e5373575c006feb04fb7d3a2706da3127c0db801b3c960697f774cd3df68df3622b975f365ed5fdfa211327aa3d3

data/Gemfile

@@ -5,7 +5,7 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem "standard", "~> 1.49"
+  gem "standard", "~> 1.54.0"
 end
 
 group :development, :test do

data/Gemfile.lock

@@ -1,18 +1,14 @@
 PATH
   remote: .
   specs:
-    courrier (0.10.0)
-      launchy (>= 3.1, < 4)
+    courrier (0.11.0)
+      logger (>= 1.5, < 3)
       nokogiri (>= 1.18, < 2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
-    childprocess (5.1.0)
-      logger (~> 1.5)
     date (3.4.1)
     debug (1.10.0)
       irb (~> 1.10)
@@ -24,18 +20,14 @@ GEM
       reline (>= 0.4.2)
     json (2.11.1)
     language_server-protocol (3.17.0.4)
-    launchy (3.1.1)
-      addressable (~> 2.8)
-      childprocess (~> 5.0)
-      logger (~> 1.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    nokogiri (1.18.8-arm64-darwin)
+    minitest (5.27.0)
+    nokogiri (1.19.3-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-darwin)
+    nokogiri (1.19.3-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.19.3-x86_64-linux-gnu)
       racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.8.0)
@@ -44,11 +36,10 @@ GEM
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.4.0)
+    prism (1.9.0)
     psych (5.2.3)
       date
       stringio
-    public_suffix (6.0.2)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
@@ -57,7 +48,7 @@ GEM
     regexp_parser (2.10.0)
     reline (0.6.1)
       io-console (~> 0.5)
-    rubocop (1.75.3)
+    rubocop (1.84.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -65,21 +56,21 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     rubocop-performance (1.25.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.49.0)
+    standard (1.54.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.2)
+      rubocop (~> 1.84.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -91,10 +82,11 @@ GEM
     stringio (3.1.7)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   arm64-darwin-23
+  arm64-darwin-24
   x86_64-darwin-23
   x86_64-linux
 
@@ -103,7 +95,7 @@ DEPENDENCIES
   debug (~> 1.9, >= 1.9.2)
   minitest (~> 5.25, >= 5.25.5)
   rake (~> 13.2, >= 13.2.1)
-  standard (~> 1.49)
+  standard (~> 1.54.0)
 
 BUNDLED WITH
    2.6.8

data/README.md

@@ -38,22 +38,24 @@ Add the gem:
 ```bash
 bundle add courrier
 ```
+> [!tip]
+> For **Rails** apps, use [`rails_courrier`](https://github.com/Rails-Designer/rails_courrier) instead. It includes generators, ActiveJob support (`deliver_later`), inbox previews and more.
 
-Generate the configuration file:
-```bash
-bin/rails generate courrier:install
-```
+Configure Courrier in your app:
+```ruby
+Courrier.configure do |config|
+  config.email = {
+    provider: "postmark",
+    api_key: "your-api-key"
+  }
 
-This creates `config/initializers/courrier.rb` for configuring email providers and default settings.
+  config.from = "devs@example.com"
+end
+```
 
 
 ## Usage
 
-Generate a new email:
-```bash
-bin/rails generate courrier:email Order
-```
-
 ```ruby
 class OrderEmail < Courrier::Email
   def subject = "Here is your order!"
@@ -91,8 +93,13 @@ Courrier.configure do |config|
   config.default_url_options = { host: "railsdesigner.com" }
 
   # Provider-specific configuration
+  config.providers.cloudflare.account_id = "your-account-id"
   config.providers.loops.transactional_id = "default-template"
   config.providers.mailgun.domain = "notifications.railsdesigner.com"
+
+  config.providers.ses.region = "us-east-1"
+  config.providers.ses.access_key_id = "your-access-key-id"
+  config.providers.ses.secret_access_key = "your-secret-access-key"
 end
 ```
 
@@ -127,11 +134,12 @@ class OrderEmail < Courrier::Email
   def subject = "Rails Icons now supports SVG sprites!"
 
   def text = # …
-  def markdown = # …
+
+  def html = # …
 end
 ```
 
-Useful for adding provider-specific headers like List-Unsubscribe for Postmark, X-Mailer identifiers, or custom metadata headers required.
+Useful for adding provider-specific headers like List-Unsubscribe for Postmark, X-Mailer identifiers or custom metadata headers required.
 
 
 ## Custom attributes
@@ -139,7 +147,7 @@ Useful for adding provider-specific headers like List-Unsubscribe for Postmark,
 Besides the standard email attributes (`from`, `to`, `reply_to`, etc.), you can pass any additional attributes that will be available in your email templates:
 ```ruby
 OrderEmail.deliver to: "recipient@railsdesigner.com",\
-                   download_url: downloads_path(token: "token")
+                   download_url: "https://example.com/download?token=abc123"
 ```
 
 These custom attributes are accessible directly in your email class:
@@ -170,7 +178,7 @@ When sending an email through Courrier, a `Result` object is returned that provi
 ### Example
 
 ```ruby
-delivery = OrderEmail.deliver(to: "recipient@example.com")
+delivery = OrderEmail.deliver to: "recipient@example.com"
 
 if delivery.success?
   puts "Email sent successfully!"
@@ -185,11 +193,17 @@ end
 
 Courrier supports these transactional email providers:
 
+- [AWS SES](https://aws.amazon.com/ses/) — requires `aws-sigv4` gem
+- [Cloudflare Email Service](https://developers.cloudflare.com/email-service/)
+- [Lettermint](https://lettermint.co)
 - [Loops](https://loops.so)
 - [Mailgun](https://mailgun.com)
 - [MailPace](https://mailpace.com)
 - [Postmark](https://postmarkapp.com)
 - [Resend](https://resend.com)
+- [SendGrid](https://sendgrid.com)
+- [SMTP2GO](https://www.smtp2go.com/)
+- [SparkPost](https://www.sparkpost.com/)
 - [Userlist](https://userlist.com)
 
 
@@ -198,36 +212,6 @@ Courrier supports these transactional email providers:
 Additional functionality to help with development and testing:
 
 
-### Background jobs (Rails only)
-
-Use `deliver_later` to enqueue delivering using Rails' ActiveJob. You can set
-various ActiveJob-supported options in the email class, like so: `enqueue queue: "emails", wait: 5.minutes`.
-
-- `queue`, enqueue the email on the specified queue;
-- `wait`, enqueue the email to be delivered with a delay;
-- `wait_until`, enqueue the email to be delivered at (after) a specific date/time;
-- `priority`, enqueues the email with the specified priority.
-
-
-### Inbox (Rails only)
-
-You can preview your emails in the inbox:
-```ruby
-config.provider = "inbox"
-
-# And add to your routes:
-mount Courrier::Engine => "/courrier"
-```
-
-If you want to automatically open every email in your default browser:
-```ruby
-config.provider = "inbox"
-config.inbox.auto_open = true
-```
-
-Emails are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
-
-
 ### Layout support
 
 Wrap your email content using layouts:
@@ -277,17 +261,18 @@ Instead of defining `text` and `html` methods, you can create ERB template files
 ```ruby
 class OrderEmail < Courrier::Email
   def subject = "Your order is ready!"
+
   # text and html content will be loaded from template files
 end
 ```
 
-Create template files alongside your email class:
-- `app/emails/order_email.text.erb`
-- `app/emails/order_email.html.erb`
+Create template files alongside your email class (default path is `courrier/emails`):
+- `courrier/emails/order_email.text.erb`
+- `courrier/emails/order_email.html.erb`
 
 Templates have access to all context options and instance variables:
 ```erb
-<!-- app/emails/order_email.html.erb -->
+<!-- courrier/emails/order_email.html.erb -->
 <h1>Hello <%= name %>!</h1>
 <p>Your order #<%= order_id %> is ready for pickup.</p>
 ```
@@ -299,7 +284,7 @@ class OrderEmail < Courrier::Email
 
   def text = "Hello #{name}! Your order ##{order_id} is ready."
 
-  # html will be loaded from app/emails/order_email.html.erb
+  # html will be loaded from courrier/emails/order_email.html.erb
 end
 ```
 
@@ -333,12 +318,12 @@ end
 
 ### Markdown templates
 
-Create markdown template files alongside your email class:
-- `app/emails/order_email.md.erb`
-- `app/emails/order_email.markdown.erb`
+Create markdown template files alongside your email class (default path is `courrier/emails`):
+- `courrier/emails/order_email.md.erb`
+- `courrier/emails/order_email.markdown.erb`
 
 ```erb
-<!-- app/emails/order_email.md.erb -->
+<!-- courrier/emails/order_email.md.erb -->
 # Hello <%= name %>!
 
 Your order **#<%= order_id %>** is ready for pickup.
@@ -355,7 +340,7 @@ Method definitions take precedence over template files. You can mix approaches.
 
 Automatically generate plain text versions from your HTML emails:
 ```ruby
-config.auto_generate_text = true # Defaults to false
+config.auto_generate_text = true  # defaults to false
 ```
 
 
@@ -363,17 +348,6 @@ config.auto_generate_text = true # Defaults to false
 
 Compose email addresses with display names:
 ```ruby
-class SignupsController < ApplicationController
-  def create
-    recipient = email_with_name("devs@railsdesigner.com", "Rails Designer Devs")
-
-    WelcomeEmail.deliver to: recipient
-  end
-end
-```
-
-In Plain Ruby Objects:
-```ruby
 class Signup
   include Courrier::Email::Address
 
@@ -391,8 +365,8 @@ end
 Use Ruby's built-in Logger for development and testing:
 
 ```ruby
-config.provider = "logger" # outputs emails to STDOUT
-config.logger = custom_logger # optional: defaults to ::Logger.new($stdout)
+config.provider = "logger"  # outputs emails to STDOUT
+config.logger = custom_logger  # optional: defaults to ::Logger.new($stdout)
 ```
 
 
@@ -417,6 +391,82 @@ config.provider = "CustomProvider"
 Check the [existing providers](https://github.com/Rails-Designer/courrier/tree/main/lib/courrier/email/providers) for implementation examples.
 
 
+### Testing
+
+Courrier provides `Test` and `TestHelper` for testing email delivery, similar to Action Mailer's testing API.
+
+Access all delivered emails:
+```ruby
+# Clear deliveries between tests
+Courrier::Test.clear!
+
+# Access all deliveries
+Courrier::Test.deliveries
+```
+
+Each delivery record contains:
+
+- `email_class`; the email class name
+- `to`, `from`, `reply_to`, `cc`, `bcc`; email addresses
+- `subject`; email subject
+- `body` - Hash with `:text` and `:html` keys
+- `headers`; custom headers
+- `provider`; provider used
+- `result`; result object with `success?` method
+- `timestamp`; delivery time
+
+Include the helper in your test class for assertions:
+```ruby
+class OrderTest < Minitest::Test
+  include Courrier::TestHelper
+
+  def setup
+    Courrier::Test.clear!
+  end
+
+  def test_sends_confirmation_email
+    order = Order.create! product: "Widget", customer_email: "customer@example.com"
+
+    OrderEmail.deliver to: order.customer_email, order: order
+
+    assert_emails_delivered 1
+    assert_email_delivered to: "customer@example.com"
+    assert_email_delivered OrderEmail, subject: "Order"
+  end
+
+  def test_no_emails_when_order_cancelled
+    order = Order.create! product: "Widget", status: :cancelled
+
+    assert_no_emails_delivered
+  end
+end
+```
+
+Available assertions:
+
+- `assert_emails_delivered(count)`; assert the number of emails delivered
+- `assert_no_emails_delivered`; assert no emails were delivered
+- `assert_email_delivered(email_class, to:, from:, subject:, provider:)`; assert an email matching criteria was delivered
+
+
+### Delivery callbacks
+
+Hook into the email delivery lifecycle with `before_deliver` and `after_deliver` callbacks:
+```ruby
+class OrderEmail < Courrier::Email
+  before_deliver do |email|
+    puts "Sending to #{email.options.to}"  # access email options, abort delivery by returning false
+  end
+
+  after_deliver do |email, result|
+    puts "Delivered: #{result.success?}"  # access email and delivery result
+  end
+end
+```
+
+Callbacks are isolated per class (subclasses don't inherit parent callbacks).
+
+
 ## Newsletter subscriptions
 
 Manage subscribers across popular email marketing platforms:
@@ -463,6 +513,7 @@ config.subscriber = {
 }
 ```
 
+
 ### Custom providers
 
 Create custom providers by inheriting from `Courrier::Subscriber::Base`:
@@ -502,17 +553,11 @@ See [existing providers](https://github.com/Rails-Designer/courrier/tree/main/li
 
 ## FAQ
 
-### Is this a replacement for ActionMailer?
-Yes! While different in approach, Courrier can fully replace ActionMailer. It's a modern alternative that focuses on API-based delivery. The main difference is in how emails are structured - Courrier uses a more straightforward, class-based approach.
-
 ### Is this for Rails only?
-Not at all! While Courrier has some Rails-specific goodies (like the inbox preview feature and generators), it works great with any Ruby application.
+Not at all! Courrier works with any Ruby application. For Rails apps, use [`rails_courrier`](https://github.com/Rails-Designer/rails_courrier).
 
 ### Can it send using SMTP?
-No. Courrier is specifically built for API-based email delivery. If SMTP is needed, ActionMailer would be a better choices.
-
-### What's the main benefit over ActionMailer?
-Courrier offers a simpler, more modern approach to sending emails. Each email is a standalone class, configuration is straightforward (typically just only an API key is needed) and it packs few quality-of-life features (like the inbox feature and auto-generate text version).
+No. Courrier is specifically built for API-based email delivery.
 
 
 ## Contributing

data/courrier.gemspec

@@ -10,16 +10,16 @@ Gem::Specification.new do |spec|
 
   spec.summary = "API-powered email delivery for Ruby apps"
   spec.description = "API-powered email delivery for Ruby apps with support for Postmark, SendGrid, Mailgun and more."
-  spec.homepage = "https://railsdesigner.com/courrier/"
+  spec.homepage = "https://railsdesigner.com/open-source/courrier/"
   spec.license = "MIT"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Rails-Designer/courrier/"
 
-  spec.files = Dir["{bin,app,config,lib}/**/*", "Rakefile", "README.md", "courrier.gemspec", "Gemfile", "Gemfile.lock"]
+  spec.files = Dir["{bin,lib}/**/*", "Rakefile", "README.md", "courrier.gemspec", "Gemfile", "Gemfile.lock"]
 
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 4.0.0"
 
-  spec.add_dependency "launchy", ">= 3.1", "< 4"
+  spec.add_dependency "logger", ">= 1.5", "< 3"
   spec.add_dependency "nokogiri", ">= 1.18", "< 2"
 end

data/lib/courrier/configuration.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "courrier/configuration/inbox"
 require "courrier/configuration/providers"
 
 module Courrier
@@ -22,7 +21,7 @@ module Courrier
     attr_accessor :email, :subscriber, :logger, :email_path, :layouts, :default_url_options, :auto_generate_text,
       :from, :reply_to, :cc, :bcc
 
-    attr_reader :providers, :inbox
+    attr_reader :providers
 
     def initialize
       @email = {provider: "logger"}
@@ -41,7 +40,6 @@ module Courrier
       @bcc = nil
 
       @providers = Courrier::Configuration::Providers.new
-      @inbox = Courrier::Configuration::Inbox.new
     end
 
     def provider
@@ -71,7 +69,7 @@ module Courrier
     private
 
     def default_email_path
-      defined?(Rails) ? Rails.root.join("app", "emails").to_s : File.join("courrier", "emails")
+      File.join("courrier", "emails")
     end
   end
 end

data/lib/courrier/email/provider.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require "courrier/email/providers/base"
-require "courrier/email/providers/inbox"
+require "courrier/email/providers/cloudflare"
+require "courrier/email/providers/lettermint"
 require "courrier/email/providers/logger"
 require "courrier/email/providers/loops"
 require "courrier/email/providers/mailgun"
@@ -9,7 +10,9 @@ require "courrier/email/providers/mailjet"
 require "courrier/email/providers/mailpace"
 require "courrier/email/providers/postmark"
 require "courrier/email/providers/resend"
+require "courrier/email/providers/ses"
 require "courrier/email/providers/sendgrid"
+require "courrier/email/providers/smtp2go"
 require "courrier/email/providers/sparkpost"
 require "courrier/email/providers/userlist"
 
@@ -17,15 +20,18 @@ module Courrier
   class Email
     class Provider
       PROVIDERS = {
-        inbox: Courrier::Email::Providers::Inbox,
+        cloudflare: Courrier::Email::Providers::Cloudflare,
         logger: Courrier::Email::Providers::Logger,
+        lettermint: Courrier::Email::Providers::Lettermint,
         loops: Courrier::Email::Providers::Loops,
         mailgun: Courrier::Email::Providers::Mailgun,
         mailjet: Courrier::Email::Providers::Mailjet,
         mailpace: Courrier::Email::Providers::Mailpace,
         postmark: Courrier::Email::Providers::Postmark,
         resend: Courrier::Email::Providers::Resend,
+        ses: Courrier::Email::Providers::Ses,
         sendgrid: Courrier::Email::Providers::Sendgrid,
+        smtp2go: Courrier::Email::Providers::Smtp2go,
         sparkpost: Courrier::Email::Providers::Sparkpost,
         userlist: Courrier::Email::Providers::Userlist
       }
@@ -72,7 +78,7 @@ module Courrier
       end
 
       def api_key_required_providers?
-        !%w[logger inbox].include?(@provider.to_s)
+        !%w[logger].include?(@provider.to_s)
       end
 
       def api_key_blank?
@@ -80,7 +86,7 @@ module Courrier
       end
 
       def production?
-        defined?(Rails) && Rails.env.production?
+        ENV["RACK_ENV"] == "production"
       end
     end
   end

data/lib/courrier/email/providers/cloudflare.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Email
+    module Providers
+      class Cloudflare < Base
+        def body
+          {
+            "from" => @options.from,
+            "to" => @options.to,
+            "reply_to" => @options.reply_to,
+            "cc" => @options.cc,
+            "bcc" => @options.bcc,
+            "subject" => @options.subject,
+            "text" => @options.text,
+            "html" => @options.html
+          }.compact
+        end
+
+        private
+
+        def endpoint_url
+          account_id = @provider_options.account_id
+          raise Courrier::ArgumentError, "Cloudflare requires an `account_id`" unless account_id
+
+          "https://api.cloudflare.com/client/v4/accounts/#{account_id}/email/sending/send"
+        end
+
+        def default_headers
+          {"Authorization" => "Bearer #{@api_key}"}
+        end
+      end
+    end
+  end
+end

data/lib/courrier/email/providers/lettermint.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Email
+    module Providers
+      class Lettermint < Base
+        ENDPOINT_URL = "https://api.lettermint.co/v1/send"
+
+        def body
+          {
+            "route" => @provider_options.route,
+            "from" => @options.from,
+            "to" => @options.to.to_s.split(",").map(&:strip),
+            "cc" => @options.cc&.split(",")&.map(&:strip),
+            "bcc" => @options.bcc&.split(",")&.map(&:strip),
+            "reply_to" => @options.reply_to&.split(",")&.map(&:strip),
+            "subject" => @options.subject,
+            "html" => @options.html,
+            "text" => @options.text
+          }.compact
+        end
+
+        private
+
+        def default_headers
+          {"x-lettermint-token" => @api_key}
+        end
+      end
+    end
+  end
+end