courrier 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555584763bab84eb75f07a5a7fa43fb4e4a65c3b1bb52de2c8e551c744fd0625
-  data.tar.gz: 4901dfab5c8c70d2f741e6c5edc0014e2aa7a9ca4afddc011d0d946464da709d
+  metadata.gz: b0a97b8804b294b065433077d025cde44716b87821214649a6421cac278beca5
+  data.tar.gz: 814110bf00d835bfacb15bc8f59bdeb04a0cb7f7b572d4418c3fd901e98c1115
 SHA512:
-  metadata.gz: 93d5a592840d197493eafc3b8cac47b03218b9d8bdce88ef2e666685468a32879583ea7bb7adc1e84a665864ee5d4aebc80e982606f78836d2cf996e7fd5e602
-  data.tar.gz: d2e4391d1ea6d24031fbba9539f4935386b552184e145a4a2582e0a9a72003d3f79ed2afc6091ca9b2f4069b725e8a778602b8d31fe688999fad2badc4535276
+  metadata.gz: fc4503ec4cef48dbd12f67f093ccb3df9b29834d34b26f99af90b8020f9be2f7207b7629be79d50ba90af9b7b01c47e104568c1813b7b5296211ed788f453831
+  data.tar.gz: d50436d4e7417f481f3f2ad2cc59962b30f42fd60d471f7226128e02e04c0378c117968a8c64c8346a735af2e1dae843d1d0447bdb9ce91153850d9e67af1d83

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 (1.0.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
 ```
 
@@ -114,12 +121,10 @@ 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:
+Email classes can define custom headers that are sent with every email:
 ```ruby
 class OrderEmail < Courrier::Email
   headers list_unsubscribe_post: "List-Unsubscribe=One-Click"
@@ -127,11 +132,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 +145,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 +176,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,109 +191,45 @@ end
 
 Courrier supports these transactional email providers:
 
+- [AWS SES](https://aws.amazon.com/ses/) — requires `aws-sigv4` gem
+- [Brevo](https://www.brevo.com/)
+- [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)
 
 
 ## More Features
 
-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:
-```ruby
-class OrderEmail < Courrier::Email
- layout text: "%{content}\n\nThanks for your order!",
-        html: "<div>\n%{content}\n</div>"
-end
-```
-
-Using a method:
-```ruby
-class OrderEmail < Courrier::Email
-  layout html: :html_layout
-
-  def html_layout
-    <<~HTML
-      <div style='font-family: ui-sans-serif, system-ui;'>
-        %{content}
-      </div>
-    HTML
-  end
-end
-```
-
-Using a separate class:
-```ruby
-class OrderEmail < Courrier::Email
-  layout html: OrderLayout
-end
-
-class OrderLayout
-  self.call
-    <<~HTML
-      <div style='font-family: ui-sans-serif, system-ui;'>
-        %{content}
-      </div>
-    HTML
-  end
-end
-```
+Additional functionality to go beyond the basics:
 
 
 ### Template files
 
 Instead of defining `text` and `html` methods, you can create ERB template files:
 ```ruby
+# courrier/emails/order_email.rb
 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,14 +241,14 @@ 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
 ```
 
 
 ## Markdown support
 
-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.
+Courrier supports rendering markdown to HTML. Bundle any supported markdown gem (`redcarpet`, `kramdown` or `commonmarker`) and it will be used.
 
 
 ### Markdown methods
@@ -333,12 +275,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.
@@ -351,28 +293,76 @@ Your order **#<%= order_id %>** is ready for pickup.
 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.
 
 
+### Layout support
+
+Wrap your email content using layouts:
+```ruby
+class OrderEmail < Courrier::Email
+ layout text: "%{content}\n\nThanks for your order!",
+        html: "<div>\n%{content}\n</div>"
+end
+```
+
+Using a method:
+```ruby
+class OrderEmail < Courrier::Email
+  layout html: :html_layout
+
+  def html_layout
+    <<~HTML
+      <div style='font-family: ui-sans-serif, system-ui;'>
+        %{content}
+      </div>
+    HTML
+  end
+end
+```
+
+Using a separate class:
+```ruby
+class OrderEmail < Courrier::Email
+  layout html: OrderLayout
+end
+
+class OrderLayout
+  self.call
+    <<~HTML
+      <div style='font-family: ui-sans-serif, system-ui;'>
+        %{content}
+      </div>
+    HTML
+  end
+end
+```
+
+
 ### Auto-generate text from HTML
 
 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
 ```
 
 
-### Email address helper
+### Delivery callbacks
 
-Compose email addresses with display names:
+Hook into the email delivery lifecycle with `before_deliver` and `after_deliver` callbacks:
 ```ruby
-class SignupsController < ApplicationController
-  def create
-    recipient = email_with_name("devs@railsdesigner.com", "Rails Designer Devs")
+class OrderEmail < Courrier::Email
+  before_deliver do |email|
+    puts "Sending to #{email.options.to}"  # access email options, abort delivery by returning false
+  end
 
-    WelcomeEmail.deliver to: recipient
+  after_deliver do |email, result|
+    puts "Delivered: #{result.success?}"  # access email and delivery result
   end
 end
 ```
 
-In Plain Ruby Objects:
+
+### Email address helper
+
+Compose email addresses with display names:
 ```ruby
 class Signup
   include Courrier::Email::Address
@@ -391,8 +381,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.email = { provider: "logger" }  # outputs emails to STDOUT
+config.logger = custom_logger  # optional: defaults to ::Logger.new($stdout)
 ```
 
 
@@ -411,15 +401,73 @@ end
 
 Then configure it:
 ```ruby
-config.provider = "CustomProvider"
+config.email = { 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
+
+
 ## Newsletter subscriptions
 
-Manage subscribers across popular email marketing platforms:
+Use Courrier to manage subscribers across popular email marketing platforms:
 ```ruby
 Courrier.configure do |config|
   config.subscriber = {
@@ -447,6 +495,7 @@ end
 ### Supported providers
 
 - [Beehiiv](https://www.beehiiv.com/) - requires `publication_id`
+- [Brevo](https://www.brevo.com/) - accepts optional `list_ids`
 - [Buttondown](https://buttondown.com)
 - [Kit](https://kit.com/) (formerly ConvertKit) - requires `form_id`
 - [Loops](https://loops.so/)
@@ -463,6 +512,15 @@ config.subscriber = {
 }
 ```
 
+For Brevo, pass one or more list IDs when new contacts should be added to specific lists:
+```ruby
+config.subscriber = {
+  provider: "brevo",
+  api_key: "your_api_key",
+  list_ids: [12, 34]
+}
+```
+
 ### Custom providers
 
 Create custom providers by inheriting from `Courrier::Subscriber::Base`:
@@ -502,17 +560,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 = ">= 3.4.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,37 +40,12 @@ module Courrier
       @bcc = nil
 
       @providers = Courrier::Configuration::Providers.new
-      @inbox = Courrier::Configuration::Inbox.new
-    end
-
-    def provider
-      warn "[DEPRECATION] `provider` is deprecated. Use `email = { provider: '…' }` instead. Will be removed in 1.0.0"
-
-      @email[:provider]
-    end
-
-    def provider=(value)
-      warn "[DEPRECATION] `provider=` is deprecated. Use `email = { provider: '…' }` instead. Will be removed in 1.0.0"
-
-      @email[:provider] = value
-    end
-
-    def api_key
-      warn "[DEPRECATION] `api_key` is deprecated. Use `email = { api_key: '…' }` instead. Will be removed in 1.0.0"
-
-      @email[:api_key]
-    end
-
-    def api_key=(value)
-      warn "[DEPRECATION] `api_key=` is deprecated. Use `email = { api_key: '…' }` instead. Will be removed in 1.0.0"
-
-      @email[:api_key] = value
     end
 
     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