courrier 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1359782140920863fe902186544d8b34bcbc513ca4412b26bc3bea975196916e
-  data.tar.gz: 493af39e04f09434689cb810a57c591b02ec9373b84660de4de0349c168eebfb
+  metadata.gz: e43b1cb6985e742ca84f68be14ddf25e72bf8f64a26ce7be151272983996ac45
+  data.tar.gz: ac7b82db6e5fd9975a76de6a630a4ac8e3f956595e175fc6d6c1ef18d9d4949c
 SHA512:
-  metadata.gz: d7928a0eb201e6b4b5e36612a03641c49a862477c6338be08800e10c1a4b9cc5f8e1917253a2a2b9b414c51ef361c9dcbfe87a309e1fcba22fb8af43310f068e
-  data.tar.gz: 9a4c22a760d6c9af901beaa076a30dcbe02db45b2c339932bef2a3e6df90531d3bdaf860c86bb954d0397243b73c4b2b07dd4072eef6cd5c9d641a9e2f3303fd
+  metadata.gz: 4f5ad1ecb424cca190a86bd10acbf69c906e3f7218724a3cdc29e8ce3e10c4bea4c1c43ba66d6de24af17f53c9db416c659e7b84aadd92fcece63b57ee5a13ce
+  data.tar.gz: 9050571fcc8050ecb6a92a321e466f92951c383d3ec1376809f70913440f38537f8245b37f2955bca3c263874d9de178818789dae89cc2a7bfe809c3d9d39eb9

data/Gemfile.lock

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

data/README.md

@@ -1,12 +1,23 @@
 # Courrier
 
-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 an API-powered 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,7 +118,7 @@ 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
@@ -122,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 |
 |:-------|:-----------|:------------|
@@ -157,22 +171,28 @@ 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)
 - [Resend](https://resend.com)
-- [SendGrid](https://sendgrid.com)
-- [SparkPost](https://sparkpost.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 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:
@@ -192,7 +212,7 @@ config.inbox.auto_open = true
 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
@@ -235,7 +255,7 @@ end
 ```
 
 
-### Auto-generate Text from HTML
+### Auto-generate text from HTML
 
 Automatically generate plain text versions from your HTML emails:
 ```ruby
@@ -243,7 +263,7 @@ config.auto_generate_text = true # Defaults to false
 ```
 
 
-### Email Address Helper
+### Email address helper
 
 Compose email addresses with display names:
 ```ruby
@@ -270,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
@@ -300,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/lib/courrier/configuration.rb

@@ -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, :inbox
 
     def initialize
-      @provider = "logger"
-      @api_key = nil
+      @email = {provider: "logger"}
+      @subscriber = {}
+
       @logger = ::Logger.new($stdout)
       @email_path = default_email_path
 
@@ -42,6 +44,30 @@ module Courrier
       @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

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:)

data/lib/courrier/email/provider.rb

@@ -16,9 +16,24 @@ require "courrier/email/providers/userlist"
 module Courrier
   class Email
     class Provider
+      PROVIDERS = {
+        inbox: Courrier::Email::Providers::Inbox,
+        logger: Courrier::Email::Providers::Logger,
+        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,
+        sendgrid: Courrier::Email::Providers::Sendgrid,
+        sparkpost: Courrier::Email::Providers::Sparkpost,
+        userlist: Courrier::Email::Providers::Userlist
+      }
+
       def initialize(provider: nil, api_key: nil, options: {}, provider_options: {}, context_options: {})
         @provider = provider
         @api_key = api_key
+
         @options = options
         @provider_options = provider_options
         @context_options = context_options
@@ -26,7 +41,7 @@ module Courrier
 
       def deliver
         raise Courrier::ConfigurationError, "`provider` and `api_key` must be configured for production environment" if configuration_missing_in_production?
-        raise Courrier::ConfigurationError, "Unknown provider. Choose one of `#{comma_separated_providers}` or provide your own." if @provider.empty? || @provider.nil?
+        raise Courrier::ConfigurationError, "Unknown provider. Choose one of `#{comma_separated_providers}` or provide your own." if @provider.nil? || @provider.to_s.strip.empty?
 
         provider_class.new(
           api_key: @api_key,
@@ -38,20 +53,6 @@ module Courrier
 
       private
 
-      PROVIDERS = {
-        inbox: Courrier::Email::Providers::Inbox,
-        logger: Courrier::Email::Providers::Logger,
-        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,
-        sendgrid: Courrier::Email::Providers::Sendgrid,
-        sparkpost: Courrier::Email::Providers::Sparkpost,
-        userlist: Courrier::Email::Providers::Userlist
-      }.freeze
-
       def configuration_missing_in_production?
         production? && required_attributes_blank?
       end

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

@@ -39,7 +39,7 @@ module Courrier
         end
 
         def prepare(content)
-          content.to_s.gsub(URI::DEFAULT_PARSER.make_regexp(%w[http https])) do |url|
+          content.to_s.gsub(URL_PARSER.make_regexp(%w[http https])) do |url|
             %(<a href="#{url}">#{url}</a>)
           end
         end
@@ -58,6 +58,10 @@ module Courrier
           "available at #{path}"
         end
 
+        URL_PARSER = (
+          defined?(URI::RFC2396_PARSER) ? URI::RFC2396_PARSER : URI::DEFAULT_PARSER
+        )
+
         class Email < Data.define(:path, :filename, :metadata)
           Metadata = Data.define(:to, :subject)
 

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

@@ -21,9 +21,7 @@ module Courrier
           <<~EMAIL
             #{separator}
             Timestamp: #{Time.now.strftime("%Y-%m-%d %H:%M:%S %z")}
-            From:      #{@options.from}
-            To:        #{@options.to}
-            Subject:   #{@options.subject}
+            #{meta_fields(from: options)}
 
             Text:
             #{@options.text || "(empty)"}
@@ -35,6 +33,27 @@ module Courrier
         end
 
         def separator = "-" * 80
+
+        def meta_fields(from:)
+          fields = [
+            [:from, "From"],
+            [:to, "To"],
+            [:reply_to, "Reply-To"],
+            [:cc, "Cc"],
+            [:bcc, "Bcc"],
+            [:subject, "Subject"]
+          ]
+
+          fields.map do |field, label|
+            value = from.send(field)
+
+            next if value.nil? || value.to_s.strip.empty?
+
+            "#{label}:".ljust(11) + value
+          rescue NoMatchingPatternError
+            nil
+          end.compact.join("\n")
+        end
       end
     end
   end

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

@@ -33,10 +33,17 @@ module Courrier
           end
         end
 
-        def text_document
+        def provider_options
+          {"theme" => nil}.merge(@provider_options)
+        end
+
+        def multipart_document
           {
-            "type" => "text",
-            "content" => @options.text
+            "type" => "multipart",
+            "content" => [
+              html_document,
+              text_document
+            ]
           }
         end
 
@@ -47,19 +54,12 @@ module Courrier
           }
         end
 
-        def multipart_document
+        def text_document
           {
-            "type" => "multipart",
-            "content" => [
-              html_document,
-              text_document
-            ]
+            "type" => "text",
+            "content" => @options.text
           }
         end
-
-        def provider_options
-          {"theme" => nil}.merge(@provider_options)
-        end
       end
     end
   end

data/lib/courrier/email.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
 require "courrier/email/address"
+require "courrier/jobs/email_delivery_job" if defined?(Rails)
 require "courrier/email/layouts"
 require "courrier/email/options"
 require "courrier/email/provider"
 
 module Courrier
   class Email
-    attr_accessor :provider, :api_key, :default_url_options, :options
+    attr_accessor :provider, :api_key, :default_url_options, :options, :queue_options
+
+    @queue_options = {}
 
     class << self
       %w[provider api_key from reply_to cc bcc layouts default_url_options].each do |attribute|
         define_method(attribute) do
           instance_variable_get("@#{attribute}") ||
             (superclass.respond_to?(attribute) ? superclass.send(attribute) : nil) ||
-            Courrier.configuration&.send(attribute)
+            (["provider", "api_key"].include?(attribute) ? Courrier.configuration&.email&.[](attribute.to_sym) : Courrier.configuration&.send(attribute))
         end
 
         define_method("#{attribute}=") do |value|
@@ -22,20 +25,35 @@ module Courrier
         end
       end
 
-      def deliver(options = {})
-        new(options).deliver_now
-      end
-      alias_method :deliver_now, :deliver
-
       def configure(**options)
         options.each { |key, value| send("#{key}=", value) if respond_to?("#{key}=") }
       end
       alias_method :set, :configure
 
-      def layout(options = {})
+      def queue_options
+        @queue_options ||= {}
+      end
+
+      attr_writer :queue_options
+
+      def enqueue(**options)
+        self.queue_options = options
+      end
+      alias_method :enqueue_with, :enqueue
+
+      def layout(**options)
         self.layouts = options
       end
 
+      def deliver(**options)
+        new(options).deliver_now
+      end
+      alias_method :deliver_now, :deliver
+
+      def deliver_later(**options)
+        new(options).deliver_later
+      end
+
       def inherited(subclass)
         super
 
@@ -48,8 +66,8 @@ module Courrier
     end
 
     def initialize(options = {})
-      @provider = options[:provider] || ENV["COURRIER_PROVIDER"] || self.class.provider || Courrier.configuration&.provider
-      @api_key = options[:api_key] || ENV["COURRIER_API_KEY"] || self.class.api_key || Courrier.configuration&.api_key
+      @provider = options[:provider] || ENV["COURRIER_PROVIDER"] || self.class.provider || Courrier.configuration&.email&.[](:provider)
+      @api_key = options[:api_key] || ENV["COURRIER_API_KEY"] || self.class.api_key || Courrier.configuration&.email&.[](:api_key)
 
       @default_url_options = self.class.default_url_options.merge(options[:default_url_options] || {})
       @context_options = options.except(:provider, :api_key, :from, :to, :reply_to, :cc, :bcc, :subject, :text, :html)
@@ -85,6 +103,30 @@ module Courrier
     end
     alias_method :deliver_now, :deliver
 
+    def deliver_later
+      if delivery_disabled?
+        Courrier.configuration&.logger&.info "[Courrier] Email delivery skipped: delivery is disabled via environment variable"
+
+        return nil
+      end
+
+      data = {
+        email_class: self.class.name,
+        provider: @provider,
+        api_key: @api_key,
+        options: @options.to_h,
+        provider_options: Courrier.configuration&.providers&.[](@provider.to_s.downcase.to_sym),
+        context_options: @context_options
+      }
+
+      job = Courrier::Jobs::EmailDeliveryJob
+      job = job.set(**self.class.queue_options) if self.class.queue_options.any?
+
+      job.perform_later(data)
+    rescue => error
+      raise Courrier::BackgroundDeliveryError, "Failed to enqueue email: #{error.message}"
+    end
+
     private
 
     def delivery_disabled?

data/lib/courrier/errors.rb

@@ -3,9 +3,11 @@
 module Courrier
   class Error < StandardError; end
 
+  class ConfigurationError < Error; end
+
   class ArgumentError < ::ArgumentError; end
 
   class NotImplementedError < ::NotImplementedError; end
 
-  class ConfigurationError < Error; end
+  class BackgroundDeliveryError < StandardError; end
 end

data/lib/courrier/jobs/email_delivery_job.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Courrier
+  module Jobs
+    class EmailDeliveryJob < ActiveJob::Base
+      def perform(data)
+        email_class = data[:email_class].constantize
+
+        email_class.new(
+          provider: data[:provider],
+          api_key: data[:api_key],
+          from: data[:options][:from],
+          to: data[:options][:to],
+          reply_to: data[:options][:reply_to],
+          cc: data[:options][:cc],
+          bcc: data[:options][:bcc],
+          provider_options: data[:provider_options],
+          context_options: data[:context_options]
+        ).deliver_now
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/result"
+
+module Courrier
+  class Subscriber
+    class Base
+      def initialize(api_key:)
+        @api_key = api_key
+      end
+
+      def create(email)
+        raise NotImplementedError
+      end
+
+      def destroy(email)
+        raise NotImplementedError
+      end
+
+      private
+
+      def request(method, url, body = nil)
+        uri = URI(url)
+        request_class = case method
+        when :post then Net::HTTP::Post
+        when :delete then Net::HTTP::Delete
+        when :put then Net::HTTP::Put
+        when :patch then Net::HTTP::Patch
+        when :get then Net::HTTP::Get
+        end
+
+        request = request_class.new(uri)
+        request.body = body.to_json if body
+
+        headers.each { |key, value| request[key] = value }
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+          http.request(request)
+        end
+
+        Courrier::Subscriber::Result.new(response: response)
+      rescue => error
+        Courrier::Subscriber::Result.new(error: error)
+      end
+
+      def headers
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/beehiiv.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Beehiiv < Base
+      ENDPOINT_URL = "https://api.beehiiv.com/v2/publications"
+
+      def create(email)
+        publication_id = Courrier.configuration.subscriber[:publication_id]
+        raise Courrier::ConfigurationError, "Beehiiv requires `publication_id` in subscriber configuration" unless publication_id
+
+        request(:post, "#{ENDPOINT_URL}/#{publication_id}/subscriptions", {"email" => email})
+      end
+
+      def destroy(email)
+        publication_id = Courrier.configuration.subscriber[:publication_id]
+        raise Courrier::ConfigurationError, "Beehiiv requires `publication_id` in subscriber configuration" unless publication_id
+
+        subscription_id = subscription_id(publication_id, email)
+        return Courrier::Subscriber::Result.new(error: StandardError.new("Subscription not found")) unless subscription_id
+
+        request(:delete, "#{ENDPOINT_URL}/#{publication_id}/subscriptions/#{subscription_id}")
+      end
+
+      private
+
+      def subscription_id(publication_id, email)
+        response = request(:get, "#{ENDPOINT_URL}/#{publication_id}/subscriptions?email=#{email}")
+
+        return nil unless response.success?
+
+        response.data.dig("data", 0, "id")
+      end
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/buttondown.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Buttondown < Base
+      ENDPOINT_URL = "https://api.buttondown.email/v1/subscribers"
+
+      def create(email)
+        request(:post, ENDPOINT_URL, {"email" => email})
+      end
+
+      def destroy(email)
+        request(:delete, "#{ENDPOINT_URL}/#{email}")
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Token #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/kit.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Kit < Base
+      ENDPOINT_URL = "https://api.convertkit.com/v3/forms"
+
+      def create(email)
+        form_id = Courrier.configuration.subscriber[:form_id]
+        raise Courrier::ConfigurationError, "Kit requires `form_id` in subscriber configuration" unless form_id
+
+        request(:post, "#{ENDPOINT_URL}/#{form_id}/subscribe", {
+          "api_key" => @api_key,
+          "email" => email
+        })
+      end
+
+      def destroy(email)
+        request(:put, "https://api.convertkit.com/v3/unsubscribe", {
+          "api_secret" => @api_key,
+          "email" => email
+        })
+      end
+
+      private
+
+      def headers
+        {
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/loops.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Loops < Base
+      ENDPOINT_URL = "https://app.loops.so/api/v1/contacts"
+
+      def create(email)
+        request(:post, "#{ENDPOINT_URL}/create", {
+          "email" => email
+        })
+      end
+
+      def destroy(email)
+        request(:post, "#{ENDPOINT_URL}/delete", {
+          "email" => email
+        })
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/mailchimp.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Mailchimp < Base
+      def create(email)
+        dc = Courrier.configuration.subscriber[:dc]
+        list_id = Courrier.configuration.subscriber[:list_id]
+
+        raise Courrier::ConfigurationError, "Mailchimp requires `dc` and `list_id` in subscriber configuration" unless dc && list_id
+
+        request(:post, "https://#{dc}.api.mailchimp.com/3.0/lists/#{list_id}/members", {
+          "email_address" => email,
+          "status" => "subscribed"
+        })
+      end
+
+      def destroy(email)
+        dc = Courrier.configuration.subscriber[:dc]
+        list_id = Courrier.configuration.subscriber[:list_id]
+
+        raise Courrier::ConfigurationError, "Mailchimp requires `dc` and `list_id` in subscriber configuration" unless dc && list_id
+
+        request(:delete, "https://#{dc}.api.mailchimp.com/3.0/lists/#{list_id}/members/#{email}")
+      end
+
+      private
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/courrier/subscriber/mailerlite.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "courrier/subscriber/base"
+
+module Courrier
+  class Subscriber
+    class Mailerlite < Base
+      ENDPOINT_URL = "https://connect.mailerlite.com/api/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
+  end
+end

data/lib/courrier/subscriber/result.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Subscriber
+    class Result
+      attr_reader :success, :response, :data, :error
+
+      def initialize(response: nil, error: nil)
+        @response = response
+        @error = error
+        @data = parsed(@response&.body)
+        @success = successful?
+      end
+
+      def success? = @success
+
+      private
+
+      def parsed(body)
+        return {} if @response.nil?
+
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      def successful?
+        return false if response_failed?
+        return @data["success"] if @data.key?("success")
+
+        (200..299).cover?(status_code)
+      end
+
+      def response_failed? = @error || @response.nil?
+
+      def status_code = @response.code.to_i
+    end
+  end
+end

data/lib/courrier/subscriber.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Subscriber
+    class << self
+      def create(email)
+        provider.create(email)
+      end
+      alias_method :add, :create
+
+      def destroy(email)
+        provider.destroy(email)
+      end
+      alias_method :delete, :destroy
+
+      private
+
+      def provider
+        @provider ||= provider_class.new(
+          api_key: Courrier.configuration.subscriber[:api_key]
+        )
+      end
+
+      def provider_class
+        provider_name = Courrier.configuration.subscriber[:provider]
+
+        return provider_name if provider_name.is_a?(Class)
+        require "courrier/subscriber/#{provider_name}"
+
+        Object.const_get("Courrier::Subscriber::#{provider_name.capitalize}")
+      end
+    end
+  end
+end

data/lib/courrier/version.rb

@@ -1,3 +1,3 @@
 module Courrier
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/courrier.rb

@@ -4,6 +4,7 @@ require "courrier/version"
 require "courrier/errors"
 require "courrier/configuration"
 require "courrier/email"
+require "courrier/subscriber"
 require "courrier/engine" if defined?(Rails)
 require "courrier/railtie" if defined?(Rails)
 

data/lib/generators/courrier/email_generator.rb

@@ -1,5 +1,7 @@
 module Courrier
   class EmailGenerator < Rails::Generators::NamedBase
+    AVAILABLE_TEMPLATES = %w[welcome password_reset]
+
     desc "Create a new Courrier Email class"
 
     source_root File.expand_path("templates", __dir__)
@@ -7,13 +9,34 @@ module Courrier
     check_class_collision suffix: "Email"
 
     class_option :skip_suffix, type: :boolean, default: false
+    class_option :template, type: :string, desc: "Template type (#{AVAILABLE_TEMPLATES.join(", ")})"
 
     def copy_mailer_file
-      template "email.rb", File.join(Courrier.configuration.email_path, class_path, "#{file_name}#{options[:skip_suffix] ? "" : "_email"}.rb")
+      template template_file, destination_path
     end
 
     private
 
+    def file_name = super.delete_suffix("_email")
+
     def parent_class = defined?(ApplicationEmail) ? ApplicationEmail : Courrier::Email
+
+    def template_file
+      if options[:template] && template_exists?("email/#{options[:template]}.rb.tt")
+        "email/#{options[:template]}.rb.tt"
+      else
+        "email.rb.tt"
+      end
+    end
+
+    def destination_path
+      File.join(Courrier.configuration.email_path, class_path, "#{file_name}#{options[:skip_suffix] ? "" : "_email"}.rb")
+    end
+
+    def template_exists?(path)
+      find_in_source_paths(path)
+    rescue
+      nil
+    end
   end
 end

data/lib/generators/courrier/templates/email/password_reset.rb.tt

@@ -0,0 +1,29 @@
+# Usage:
+#
+# PasswordResetEmail.deliver to: user.email, reset_url: edit_password_url(user.password_reset_token)
+#
+class <%= class_name %><%= options[:skip_suffix] ? "" : "Email" %> < <%= parent_class %>
+  def subject = "Reset your password"
+
+  def text
+    <<~TEXT
+      You can reset your password within the next 15 minutes on this password reset page:
+      #{reset_url}
+
+      If you didn't request a password reset, please ignore this email.
+    TEXT
+  end
+
+  def html
+    <<~HTML
+      <p>
+        You can reset your password within the next 15 minutes on
+        <a href="#{reset_url}">this password reset page</a>.
+      </p>
+
+      <p>
+        If you didn't request a password reset, please ignore this email.
+      </p>
+    HTML
+  end
+end

data/lib/generators/courrier/templates/email/welcome.rb.tt

@@ -0,0 +1,43 @@
+# Usage:
+#
+# WelcomeEmail.deliver to: user.email, name: "John", login_url: "https://example.com/login"
+#
+class <%= class_name %><%= options[:skip_suffix] ? "" : "Email" %> < <%= parent_class %>
+  def subject = "Welcome to My First App, #{name}!"
+
+  def text
+    <<~TEXT
+      Welcome, #{name}!
+
+      We're excited to have you on board. Here's how to get started:
+
+      1. Log in to your account: #{login_url}
+      2. Complete your profile
+      3. Explore our features
+
+      If you have any questions, our help center is available to assist you.
+
+      Thanks for joining us!
+    TEXT
+  end
+
+  def html
+    <<~HTML
+      <p>Welcome, #{name}!</p>
+
+      <p>We're excited to have you on board. Here's how to get started:</p>
+
+      <ol>
+        <li><a href="#{login_url}">Log in to your account</a></li>
+        <li>Complete your profile</li>
+        <li>Explore our features</li>
+      </ol>
+
+      <p>If you have any questions, our help center is available to assist you.</p>
+
+      <p>
+        Thanks for joining us!
+      </p>
+    HTML
+  end
+end

data/lib/generators/courrier/templates/initializer.rb.tt

@@ -1,12 +1,17 @@
 Courrier.configure do |config|
   include Courrier::Email::Address
 
-  # Choose your email delivery provider
-  # Default: `logger`
-  # config.provider = ""
+  # Set your email delivery provider
+  # config.email = {
+    # provider = "", # default, `logger`, choose from: <%= Courrier::Email::Provider::PROVIDERS.keys.join(", ") %>
+    # api_key = "" your transactional email provider's API key
+  }
+
+  # Set your marketing email provider
+  # config.subscriber = {
+    # provider = ""
+  }
 
-  # Add your email provider's API key
-  # config.api_key = ""
 
   # Configure provider-specific settings
   # config.providers.loops.transactional_id = ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: courrier
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Rails Designer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-13 00:00:00.000000000 Z
+date: 2025-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchy
@@ -97,12 +97,24 @@ files:
 - lib/courrier/email/transformer.rb
 - lib/courrier/engine.rb
 - lib/courrier/errors.rb
+- lib/courrier/jobs/email_delivery_job.rb
 - lib/courrier/railtie.rb
+- lib/courrier/subscriber.rb
+- lib/courrier/subscriber/base.rb
+- lib/courrier/subscriber/beehiiv.rb
+- lib/courrier/subscriber/buttondown.rb
+- lib/courrier/subscriber/kit.rb
+- lib/courrier/subscriber/loops.rb
+- lib/courrier/subscriber/mailchimp.rb
+- lib/courrier/subscriber/mailerlite.rb
+- lib/courrier/subscriber/result.rb
 - lib/courrier/tasks/courrier.rake
 - lib/courrier/version.rb
 - lib/generators/courrier/email_generator.rb
 - lib/generators/courrier/install_generator.rb
 - lib/generators/courrier/templates/email.rb.tt
+- lib/generators/courrier/templates/email/password_reset.rb.tt
+- lib/generators/courrier/templates/email/welcome.rb.tt
 - lib/generators/courrier/templates/initializer.rb.tt
 homepage: https://railsdesigner.com/courrier/
 licenses: