courrier 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3d93b4337d15e066ffa7ed4626dd254231ee744940de07b7b76be8714afbde
-  data.tar.gz: d7ef7a3ed1a8600581b6bdf13f63072c49ad138ad52384e1c358dbcd8f8a45b2
+  metadata.gz: d793cbc73ad9612cbb5e010e6aed85f9885e41fc8b672d16f82a6d155f63b726
+  data.tar.gz: 1143fc17abc330c3f94192ec95aea7618583266491f109b62aee3178826ede97
 SHA512:
-  metadata.gz: 32d2fba728012eb703ca67044484a2f0caf0177ee0f341b6973566a50136f6531dfc37edfe7347511b4de67291af0364f6f03ad4c22247f5bbd72ca306e13455
-  data.tar.gz: 5a3ea2ea5fb0637f025a3577d6e1004a66478e0929b96752b0fdea302af95f6c88af3bed801265dc14f6645a8014adb781cd1cc04ee1809bedf76ca892f4c4f0
+  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.9.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!"
@@ -74,8 +76,6 @@ end
 # OrderEmail.deliver to: "recipient@railsdesigner.com"
 ```
 
-💡 Write your email content using the [Minimal Email Editor](https://railsdesigner.com/minimal-email-editor/).
-
 
 ## Configuration
 
@@ -93,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
 ```
 
@@ -119,12 +124,30 @@ OrderEmail.deliver to: "recipient@railsdesigner.com",\
 Provider and API key settings can be overridden using environment variables (`COURRIER_PROVIDER` and `COURRIER_API_KEY`) for both global configuration and email class defaults.
 
 
+## Custom headers
+
+Email classes can define custom HTTP headers that are sent with every email:
+```ruby
+class OrderEmail < Courrier::Email
+  headers list_unsubscribe_post: "List-Unsubscribe=One-Click"
+
+  def subject = "Rails Icons now supports SVG sprites!"
+
+  def text = # …
+
+  def html = # …
+end
+```
+
+Useful for adding provider-specific headers like List-Unsubscribe for Postmark, X-Mailer identifiers or custom metadata headers required.
+
+
 ## Custom attributes
 
 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:
@@ -155,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!"
@@ -170,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)
 
 
@@ -183,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:
@@ -262,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>
 ```
@@ -284,33 +284,69 @@ 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
 ```
 
 
-### Auto-generate text from HTML
+## Markdown support
 
-Automatically generate plain text versions from your HTML emails:
-```ruby
-config.auto_generate_text = true # Defaults to false
-```
+Courrier supports rendering markdown content to HTML when a markdown gem is available. Simply bundle any supported markdown gem (`redcarpet`, `kramdown` or `commonmarker`) and it will be used.
 
 
-### Email address helper
+### Markdown methods
 
-Compose email addresses with display names:
+Define a `markdown` method in your email class:
 ```ruby
-class SignupsController < ApplicationController
-  def create
-    recipient = email_with_name("devs@railsdesigner.com", "Rails Designer Devs")
+class OrderEmail < Courrier::Email
+  def subject = "Your order is ready!"
 
-    WelcomeEmail.deliver to: recipient
+  def markdown
+    <<~MARKDOWN
+      # Hello #{name}!
+
+      Your order **##{order_id}** is ready for pickup.
+
+      ## Order Details
+      - Item: #{item_name}
+      - Price: #{price}
+    MARKDOWN
   end
 end
 ```
 
-In Plain Ruby Objects:
+
+### Markdown templates
+
+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
+<!-- courrier/emails/order_email.md.erb -->
+# Hello <%= name %>!
+
+Your order **#<%= order_id %>** is ready for pickup.
+
+## Order Details
+- Item: <%= item_name %>
+- Price: <%= price %>
+```
+
+Method definitions take precedence over template files. You can mix approaches. For example, define `text` in a method and use a markdown template for HTML content.
+
+
+### Auto-generate text from HTML
+
+Automatically generate plain text versions from your HTML emails:
+```ruby
+config.auto_generate_text = true  # defaults to false
+```
+
+
+### Email address helper
+
+Compose email addresses with display names:
 ```ruby
 class Signup
   include Courrier::Email::Address
@@ -329,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)
 ```
 
 
@@ -355,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:
@@ -401,6 +513,7 @@ config.subscriber = {
 }
 ```
 
+
 ### Custom providers
 
 Create custom providers by inheriting from `Courrier::Subscriber::Base`:
@@ -440,20 +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.
-
-### Can separate view templates be created (like ActionMailer)?
-The approach is different here. Instead of separate view files, email content is defined right in the email class using `text` and `html` methods. Layouts can be used to share common templates. This makes emails more self-contained and easier to reason about.
-
-### 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,26 +20,30 @@ 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
       }
 
-      def initialize(provider: nil, api_key: nil, options: {}, provider_options: {}, context_options: {})
+      def initialize(provider: nil, api_key: nil, options: {}, provider_options: {}, context_options: {}, custom_headers: {})
         @provider = provider
         @api_key = api_key
 
         @options = options
         @provider_options = provider_options
         @context_options = context_options
+        @custom_headers = custom_headers
       end
 
       def deliver
@@ -47,7 +54,8 @@ module Courrier
           api_key: @api_key,
           options: @options,
           provider_options: @provider_options,
-          context_options: @context_options
+          context_options: @context_options,
+          custom_headers: @custom_headers
         ).deliver
       end
 
@@ -70,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?
@@ -78,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/base.rb

@@ -6,11 +6,12 @@ module Courrier
   class Email
     module Providers
       class Base
-        def initialize(api_key: nil, options: {}, provider_options: {}, context_options: {})
+        def initialize(api_key: nil, options: {}, provider_options: {}, context_options: {}, custom_headers: {})
           @api_key = api_key
           @options = options
           @provider_options = provider_options
           @context_options = context_options
+          @custom_headers = custom_headers
         end
 
         def deliver
@@ -31,7 +32,11 @@ module Courrier
 
         def content_type = "application/json"
 
-        def headers = {}
+        def headers
+          default_headers.merge(@custom_headers)
+        end
+
+        def default_headers = {}
 
         def provider = self.class.name.split("::").last
       end