courrier 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2da5fe5fc7bb657449ed12d90c8443d6fa692339f9974fcbda7c4c726964ad8
-  data.tar.gz: ad4fc570a0bdb7cb1bce3c214a21e550a725212e0f900e5d31fe1345d5c7b221
+  metadata.gz: e43b1cb6985e742ca84f68be14ddf25e72bf8f64a26ce7be151272983996ac45
+  data.tar.gz: ac7b82db6e5fd9975a76de6a630a4ac8e3f956595e175fc6d6c1ef18d9d4949c
 SHA512:
-  metadata.gz: 7170f0e34c59ceee7b88c41865da67f558357058651a9508578adb5b0fec0d5da78bea1672aed8b24335128822784c1e5b23478804fb1a08273efece5129ae3f
-  data.tar.gz: 89de9523761715879b487d62ca63576eb9783647a0e2d8baba5ef268b36c91d359d96c33386b06a3cd686af8e747cf548eaf74ea9654efde22030a52eaac5fe4
+  metadata.gz: 4f5ad1ecb424cca190a86bd10acbf69c906e3f7218724a3cdc29e8ce3e10c4bea4c1c43ba66d6de24af17f53c9db416c659e7b84aadd92fcece63b57ee5a13ce
+  data.tar.gz: 9050571fcc8050ecb6a92a321e466f92951c383d3ec1376809f70913440f38537f8245b37f2955bca3c263874d9de178818789dae89cc2a7bfe809c3d9d39eb9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    courrier (0.6.0)
+    courrier (0.8.0)
       launchy (>= 3.1, < 4)
       nokogiri (>= 1.18, < 2)
 

data/README.md

@@ -1,12 +1,23 @@
 # Courrier
 
-Modern, API-powered email delivery for Ruby apps.
+API-powered email delivery and newsletter subscription management for Ruby apps
 
-![A cute cartoon mascot wearing a blue postal uniform with red scarf and cap, carrying a leather messenger bag, representing a modern email delivery system for Ruby applications](https://raw.githubusercontent.com/Rails-Designer/courrier/HEAD/.github/cover.jpg)
+![A cute cartoon mascot wearing a blue postal uniform with red scarf and cap, carrying a leather messenger bag, representing an API-powered email delivery gem for Ruby apps](https://raw.githubusercontent.com/Rails-Designer/courrier/HEAD/.github/cover.jpg)
 
 ```ruby
 # Quick example
+class OrderEmail < Courrier::Email
+  def subject = "Here is your order!"
+
+  def text = "Thanks for ordering"
+
+  def html = "<p>Thanks for ordering</p>"
+end
+
 OrderEmail.deliver to: "recipient@railsdesigner.com"
+
+# Manage newsletter subscriptions
+Courrier::Subscriber.create "subscriber@example.com"
 ```
 
 <a href="https://railsdesigner.com/" target="_blank">
@@ -72,8 +83,11 @@ Courrier uses a configuration system with three levels (from lowest to highest p
 1. **Global configuration**
 ```ruby
 Courrier.configure do |config|
-  config.provider = "postmark"
-  config.api_key = "xyz"
+  config.email = {
+    provider: "postmark",
+    api_key: "xyz"
+  }
+
   config.from = "devs@railsdesigner.com"
   config.default_url_options = { host: "railsdesigner.com" }
 
@@ -88,7 +102,7 @@ end
 class OrderEmail < Courrier::Email
   configure from: "orders@railsdesigner.com",
             cc: "records@railsdesigner.com",
-            provider: "mailgun",
+            provider: "mailgun"
 end
 ```
 
@@ -104,11 +118,12 @@ 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 Attributes
+## 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")
+OrderEmail.deliver to: "recipient@railsdesigner.com",\
+                   download_url: downloads_path(token: "token")
 ```
 
 These custom attributes are accessible directly in your email class:
@@ -121,12 +136,12 @@ end
 ```
 
 
-## Result Object
+## Result object
 
 When sending an email through Courrier, a `Result` object is returned that provides information about the delivery attempt. This object offers a simple interface to check the status and access response data.
 
 
-### Available Methods
+### Available methods
 
 | Method | Return Type | Description |
 |:-------|:-----------|:------------|
@@ -156,32 +171,48 @@ Courrier supports these transactional email providers:
 
 - [Loops](https://loops.so)
 - [Mailgun](https://mailgun.com)
-- [Mailjet](https://mailjet.com)
 - [MailPace](https://mailpace.com)
 - [Postmark](https://postmarkapp.com)
-- [SendGrid](https://sendgrid.com)
-- [SparkPost](https://sparkpost.com)
+- [Resend](https://resend.com)
 - [Userlist](https://userlist.com)
 
-⚠️ Some providers still need manual verification of their implementation. If you're using one of these providers, please help verify the implementation by sharing your experience in [this GitHub issue](https://github.com/Rails-Designer/courrier/issues/4). 🙏
-
 
 ## More Features
 
-Additional functionality to help with development and email handling:
+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"
 
-### Email Preview
+# And add to your routes:
+mount Courrier::Engine => "/courrier"
+```
 
-Preview emails in your browser during development:
+If you want to automatically open every email in your default browser:
 ```ruby
-config.provider = "preview" # Opens emails in your default browser
+config.provider = "inbox"
+config.inbox.auto_open = true
 ```
 
-Previews are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
+Emails are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
 
 
-### Layout Support
+### Layout support
 
 Wrap your email content using layouts:
 ```ruby
@@ -224,7 +255,7 @@ end
 ```
 
 
-### Auto-generate Text from HTML
+### Auto-generate text from HTML
 
 Automatically generate plain text versions from your HTML emails:
 ```ruby
@@ -232,7 +263,7 @@ config.auto_generate_text = true # Defaults to false
 ```
 
 
-### Email Address Helper
+### Email address helper
 
 Compose email addresses with display names:
 ```ruby
@@ -259,16 +290,17 @@ end
 ```
 
 
-### Logger Provider
+### Logger provider
 
 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)
 ```
 
-### Custom Providers
+
+### Custom providers
 
 Create your own provider by inheriting from `Courrier::Email::Providers::Base`:
 ```ruby
@@ -289,6 +321,107 @@ config.provider = "CustomProvider"
 Check the [existing providers](https://github.com/Rails-Designer/courrier/tree/main/lib/courrier/email/providers) for implementation examples.
 
 
+## Newsletter subscriptions
+
+Manage subscribers across popular email marketing platforms:
+```ruby
+Courrier.configure do |config|
+  config.subscriber = {
+    provider: "buttondown",
+    api_key: "your_api_key"
+  }
+end
+```
+
+```ruby
+# Add a subscriber
+subscriber = Courrier::Subscriber.create "subscriber@example.com"
+
+# Remove a subscriber
+subscriber = Courrier::Subscriber.destroy "subscriber@example.com"
+
+if subscriber.success?
+  puts "Subscriber added!"
+else
+  puts "Error: #{subscriber.error}"
+end
+```
+
+
+### Supported providers
+
+- [Beehiiv](https://www.beehiiv.com/) - requires `publication_id`
+- [Buttondown](https://buttondown.com)
+- [Kit](https://kit.com/) (formerly ConvertKit) - requires `form_id`
+- [Loops](https://loops.so/)
+- [Mailchimp](https://mailchimp.com/) - requires `dc` and `list_id`
+- [MailerLite](https://www.mailerlite.com/)
+
+Provider-specific configuration:
+```ruby
+config.subscriber = {
+  provider: "mailchimp",
+  api_key: "your_api_key",
+  dc: "us19",
+  list_id: "abc123"
+}
+```
+
+### Custom providers
+
+Create custom providers by inheriting from `Courrier::Subscriber::Base`:
+```ruby
+class CustomSubscriberProvider < Courrier::Subscriber::Base
+  ENDPOINT_URL = "https://api.example.com/subscribers"
+
+  def create(email)
+    request(:post, ENDPOINT_URL, {"email" => email})
+  end
+
+  def destroy(email)
+    request(:delete, "#{ENDPOINT_URL}/#{email}")
+  end
+
+  private
+
+  def headers
+    {
+      "Authorization" => "Bearer #{@api_key}",
+      "Content-Type" => "application/json"
+    }
+  end
+end
+```
+
+Then configure it:
+```ruby
+config.subscriber = {
+  provider: CustomSubscriberProvider,
+  api_key: "your_api_key"
+}
+```
+
+See [existing providers](https://github.com/Rails-Designer/courrier/tree/main/lib/courrier/subscriber) for more examples.
+
+
+## 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.
+
+### 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).
+
+
 ## Contributing
 
 This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `rake` before submitting pull requests.

data/app/controllers/courrier/previews/cleanups_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Courrier
+  module Previews
+    class CleanupsController < ActionController::Base
+      def create
+        system("bin/rails courrier:clear")
+
+        redirect_to root_path
+      end
+    end
+  end
+end

data/app/controllers/courrier/previews_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Courrier
+  class PreviewsController < ActionController::Base
+    def index
+      @emails = emails.map { Courrier::Email::Providers::Inbox::Email.from_file(_1) }
+    end
+
+    def show
+      file_path = File.join(Courrier.configuration.inbox.destination, params[:id])
+      content = File.read(file_path)
+
+      render html: content.html_safe, layout: false
+    end
+
+    private
+
+    def emails
+      @emails ||= Dir.glob("#{Courrier.configuration.inbox.destination}/*.html")
+        .sort_by { -File.basename(_1, ".html").to_i }
+    end
+  end
+end

data/app/views/courrier/previews/index.html.erb

@@ -0,0 +1,171 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title>Courrier Inbox</title>
+
+    <style>
+      *, *::before, *::after { box-sizing: border-box; }
+      * { margin: 0; padding: 0; }
+      body { margin: 0; padding: 0; font-size: 16px; line-height: 1.5; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; background-color: rgb(241,  245, 249); }
+
+      .sidebar {
+        display: flex;
+        flex-direction: column;
+        position: sticky;
+        top: 0;
+        padding: .5rem;
+        width: min(350px, 33.3333%); height: 100dvh;
+        border-right: 1px solid rgb(226, 232, 240);
+      }
+
+      .sidebar__options {
+        position: sticky;
+        bottom: 0;
+        padding: .5rem;
+        background-color: rgb(241, 245, 249);
+      }
+
+      .sidebar__btn-clear {
+        border: none;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        column-gap: 0.25rem;
+        width: 100%;
+        padding: .5rem;
+        font-size: .875rem; line-height: 1.25rem;
+        font-weight: 500;
+        color: rgb(71, 85, 105);
+        background-color: rgb(226, 232, 240);
+        border-radius: .5rem;
+        cursor: default;
+
+        &:hover { background-color: rgb(203, 213, 225); }
+        &:active { transform: scale(.98); }
+
+        [data-slot="icon"] {
+          width: .875rem; height: .875rem;
+        }
+      }
+
+      .email-previews {
+        display: flex;
+        flex-direction: column;
+        flex: 1;
+        row-gap: .5rem;
+        overflow-y: auto;
+        width: 100%;
+      }
+
+      .email-preview {
+        display: flex;
+        flex-direction: row;
+        column-gap: .5rem;
+        width: 100%;
+        padding: .5rem .75rem;
+        text-decoration: none;
+        border-radius: .5rem;
+
+        &:hover {
+          background-color: rgba(226, 232, 240, .75);
+        }
+      }
+
+      .email-preview--empty {
+        display: none;
+        text-align: center;
+
+        &:only-child {
+          display: block;
+        }
+      }
+
+      .email-preview__avatar {
+        flex-shrink: 0;
+        padding: .25rem;
+        width: 1.5rem; height: 1.5rem;
+        background-color: rgb(203, 213, 225);
+        color: rgb(51, 65, 85);
+        border-radius: 9999px;
+      }
+
+      .email-preview__content {
+        font-size: 0.875rem; line-height: 1.25rem;
+      }
+
+      .email-preview__recipient {
+        font-size: 1rem; line-height: 1.5rem;
+        font-weight: 600;
+        letter-spacing: -.025em;
+        color: rgb(51, 65, 85);
+      }
+
+      .email-preview__subject {
+        margin-top: .125rem;
+        overflow: hidden; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 1;
+        color: rgb(100, 116, 139);
+      }
+    </style>
+  </head>
+  <body>
+    <div style="display: flex; column-gap: 1rem;">
+      <aside class="sidebar">
+        <ul class="email-previews">
+          <li class="email-preview--empty">
+            <p class="email-preview__subject">
+              No emails yet…
+            </p>
+          </li>
+
+          <% @emails.each do |email| %>
+            <li>
+              <%= link_to courrier.preview_path(email.filename), data: {remote: true}, class: "email-preview" do %>
+                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" data-slot="icon" class="email-preview__avatar">
+                  <path fill-rule="evenodd" d="M7.5 6a4.5 4.5 0 1 1 9 0 4.5 4.5 0 0 1-9 0ZM3.751 20.105a8.25 8.25 0 0 1 16.498 0 .75.75 0 0 1-.437.695A18.683 18.683 0 0 1 12 22.5c-2.786 0-5.433-.608-7.812-1.7a.75.75 0 0 1-.437-.695Z" clip-rule="evenodd"/>
+                </svg>
+
+                <div class="email-preview__content">
+                  <small class="email-preview__recipient">
+                    <%= email.metadata.to %>
+                  </small>
+
+                  <p class="email-preview__subject">
+                    <%= email.metadata.subject || "No subject" %>
+                  </p>
+                </div>
+              <% end %>
+            </li>
+          <% end %>
+        </ul>
+
+        <div class="sidebar__options">
+          <%= button_to courrier.cleanup_path, class: "sidebar__btn-clear" do %>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" data-slot="icon">
+              <path fill-rule="evenodd" d="M16.5 4.478v.227a48.816 48.816 0 0 1 3.878.512.75.75 0 1 1-.256 1.478l-.209-.035-1.005 13.07a3 3 0 0 1-2.991 2.77H8.084a3 3 0 0 1-2.991-2.77L4.087 6.66l-.209.035a.75.75 0 0 1-.256-1.478A48.567 48.567 0 0 1 7.5 4.705v-.227c0-1.564 1.213-2.9 2.816-2.951a52.662 52.662 0 0 1 3.369 0c1.603.051 2.815 1.387 2.815 2.951Zm-6.136-1.452a51.196 51.196 0 0 1 3.273 0C14.39 3.05 15 3.684 15 4.478v.113a49.488 49.488 0 0 0-6 0v-.113c0-.794.609-1.428 1.364-1.452Zm-.355 5.945a.75.75 0 1 0-1.5.058l.347 9a.75.75 0 1 0 1.499-.058l-.346-9Zm5.48.058a.75.75 0 1 0-1.498-.058l-.347 9a.75.75 0 0 0 1.5.058l.345-9Z" clip-rule="evenodd"/>
+            </svg>
+
+            Clear inbox
+          <% end %>
+        </div>
+      </aside>
+
+      <article style="flex: 1;" id="email-preview">
+      </article>
+    </div>
+
+    <script>
+      document.querySelectorAll("a[data-remote]").forEach(link => {
+        link.addEventListener("click", (event) => {
+          event.preventDefault();
+
+          fetch(link.href)
+            .then(response => response.text())
+            .then(html => {
+              document.getElementById("email-preview").innerHTML = html;
+            });
+        });
+      });
+    </script>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Courrier::Engine.routes.draw do
+  resources :previews, only: %w[show], constraints: {id: /.*\.html/}
+  resource :cleanup, only: %w[create], module: "previews"
+
+  root "previews#index"
+end

data/courrier.gemspec

@@ -8,15 +8,15 @@ Gem::Specification.new do |spec|
   spec.authors = ["Rails Designer"]
   spec.email = ["devs@railsdesigner.com"]
 
-  spec.summary = "Modern, API-powered email delivery for Rails apps"
-  spec.description = "Modern, API-powered email delivery for Ruby apps with support for Postmark, SendGrid, Mailgun and more."
+  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.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,db,lib,public}/**/*", "Rakefile", "README.md", "courrier.gemspec", "Gemfile", "Gemfile.lock"]
+  spec.files = Dir["{bin,app,config,lib}/**/*", "Rakefile", "README.md", "courrier.gemspec", "Gemfile", "Gemfile.lock"]
 
   spec.required_ruby_version = ">= 3.2.0"
 

data/lib/courrier/configuration/{preview.rb → inbox.rb}

@@ -2,13 +2,13 @@
 
 module Courrier
   class Configuration
-    class Preview
+    class Inbox
       attr_accessor :destination, :auto_open, :template_path
 
       def initialize
         @destination = default_destination
-        @auto_open = true
-        @template_path = File.expand_path("../../../courrier/email/providers/preview/default.html.erb", __FILE__)
+        @auto_open = false
+        @template_path = File.expand_path("../../../courrier/email/providers/inbox/default.html.erb", __FILE__)
       end
 
       private

data/lib/courrier/configuration.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "courrier/configuration/preview"
+require "courrier/configuration/inbox"
 require "courrier/configuration/providers"
 
 module Courrier
@@ -19,13 +19,15 @@ module Courrier
   end
 
   class Configuration
-    attr_accessor :provider, :api_key, :logger, :email_path, :layouts, :default_url_options, :auto_generate_text,
+    attr_accessor :email, :subscriber, :logger, :email_path, :layouts, :default_url_options, :auto_generate_text,
       :from, :reply_to, :cc, :bcc
-    attr_reader :providers, :preview
+
+    attr_reader :providers, :inbox
 
     def initialize
-      @provider = "logger"
-      @api_key = nil
+      @email = {provider: "logger"}
+      @subscriber = {}
+
       @logger = ::Logger.new($stdout)
       @email_path = default_email_path
 
@@ -39,7 +41,31 @@ module Courrier
       @bcc = nil
 
       @providers = Courrier::Configuration::Providers.new
-      @preview = Courrier::Configuration::Preview.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

data/lib/courrier/email/options.rb

@@ -31,6 +31,21 @@ module Courrier
 
       def html = wrap(@html, with_layout: :html)
 
+      def to_h
+        {
+          from: @from,
+          to: @to,
+          reply_to: @reply_to,
+          cc: @cc,
+          bcc: @bcc,
+          subject: @subject,
+          text: @text,
+          html: @html,
+          auto_generate_text: @auto_generate_text,
+          layouts: @layouts
+        }
+      end
+
       private
 
       def wrap(content, with_layout:)