courrier 0.8.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3623ab587d2595e03eb10475ceab33725e643de6aa50fcd06641f6b0fb1686e0
-  data.tar.gz: 8c650ed796a0a76fa2bca4fde2dde15854faad797b90fd0f7819e4dac2f0464b
+  metadata.gz: 555584763bab84eb75f07a5a7fa43fb4e4a65c3b1bb52de2c8e551c744fd0625
+  data.tar.gz: 4901dfab5c8c70d2f741e6c5edc0014e2aa7a9ca4afddc011d0d946464da709d
 SHA512:
-  metadata.gz: ec2d11842243f85c194c69e5ca1abf8117e7026c84f62e46627a462512caa5f357bfa94eceb4a2856e11a9176b3702c609bd838798902146f115c1362aa4cf6c
-  data.tar.gz: cacb341339ad98c2cb34abd0fe81f92a2a95891ba6814331e1c1caadc46f4929319fa11a6118cf622ee6f96b036e562ff76eba1fd1b5b9dec947c6db8ad4219f
+  metadata.gz: 93d5a592840d197493eafc3b8cac47b03218b9d8bdce88ef2e666685468a32879583ea7bb7adc1e84a665864ee5d4aebc80e982606f78836d2cf996e7fd5e602
+  data.tar.gz: d2e4391d1ea6d24031fbba9539f4935386b552184e145a4a2582e0a9a72003d3f79ed2afc6091ca9b2f4069b725e8a778602b8d31fe688999fad2badc4535276

data/Gemfile.lock

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

data/README.md

@@ -74,8 +74,6 @@ end
 # OrderEmail.deliver to: "recipient@railsdesigner.com"
 ```
 
-💡 Write your email content using the [Minimal Email Editor](https://railsdesigner.com/minimal-email-editor/).
-
 
 ## Configuration
 
@@ -119,6 +117,23 @@ 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 markdown = # …
+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:
@@ -256,6 +271,86 @@ end
 ```
 
 
+### Template files
+
+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`
+
+Templates have access to all context options and instance variables:
+```erb
+<!-- app/emails/order_email.html.erb -->
+<h1>Hello <%= name %>!</h1>
+<p>Your order #<%= order_id %> is ready for pickup.</p>
+```
+
+Method definitions take precedence over template files when both exist. You can mix approaches. For example, define text in a method and use a template for the html:
+```ruby
+class OrderEmail < Courrier::Email
+  def subject = "Your order is ready!"
+
+  def text = "Hello #{name}! Your order ##{order_id} is ready."
+
+  # html will be loaded from app/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.
+
+
+### Markdown methods
+
+Define a `markdown` method in your email class:
+```ruby
+class OrderEmail < Courrier::Email
+  def subject = "Your order is ready!"
+
+  def markdown
+    <<~MARKDOWN
+      # Hello #{name}!
+
+      Your order **##{order_id}** is ready for pickup.
+
+      ## Order Details
+      - Item: #{item_name}
+      - Price: #{price}
+    MARKDOWN
+  end
+end
+```
+
+
+### Markdown templates
+
+Create markdown template files alongside your email class:
+- `app/emails/order_email.md.erb`
+- `app/emails/order_email.markdown.erb`
+
+```erb
+<!-- app/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:
@@ -414,10 +509,7 @@ Yes! While different in approach, Courrier can fully replace ActionMailer. It's
 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.
+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).

data/lib/courrier/email/provider.rb

@@ -30,31 +30,37 @@ module Courrier
         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
-        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.nil? || @provider.to_s.strip.empty?
+        raise Courrier::ConfigurationError, "Unknown provider. Choose one of `#{comma_separated_providers}` or provide your own." if provider_invalid?
+        raise Courrier::ConfigurationError, "API key must be configured for #{@provider} provider in production environment" if configuration_missing_in_production?
 
         provider_class.new(
           api_key: @api_key,
           options: @options,
           provider_options: @provider_options,
-          context_options: @context_options
+          context_options: @context_options,
+          custom_headers: @custom_headers
         ).deliver
       end
 
       private
 
+      def provider_invalid?
+        @provider.nil? || @provider.to_s.strip.empty?
+      end
+
       def configuration_missing_in_production?
-        production? && required_attributes_blank?
+        production? && api_key_required_providers? && api_key_blank?
       end
 
       def comma_separated_providers = PROVIDERS.keys.join(", ")
@@ -65,7 +71,13 @@ module Courrier
         Object.const_get(@provider)
       end
 
-      def required_attributes_blank? = @api_key.empty?
+      def api_key_required_providers?
+        !%w[logger inbox].include?(@provider.to_s)
+      end
+
+      def api_key_blank?
+        @api_key.nil? || @api_key.to_s.strip.empty?
+      end
 
       def production?
         defined?(Rails) && Rails.env.production?

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

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

@@ -16,7 +16,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Bearer #{@api_key}"
           }

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

@@ -29,7 +29,7 @@ module Courrier
 
         def content_type = "multipart/form-data"
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Basic #{Base64.strict_encode64("api:#{@api_key}")}"
           }

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

@@ -31,7 +31,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Basic " + Base64.strict_encode64("#{@api_key}:#{@provider_options.api_secret}")
           }

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

@@ -21,7 +21,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "MailPace-Server-Token" => @api_key
           }

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

@@ -23,7 +23,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "X-Postmark-Server-Token" => @api_key
           }

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

@@ -21,7 +21,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Bearer #{@api_key}"
           }

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

@@ -38,7 +38,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Bearer #{@api_key}"
           }

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

@@ -27,7 +27,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => @api_key
           }

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

@@ -17,7 +17,7 @@ module Courrier
 
         private
 
-        def headers
+        def default_headers
           {
             "Authorization" => "Push #{@api_key}"
           }

data/lib/courrier/email.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "erb"
+
 require "courrier/email/address"
 require "courrier/jobs/email_delivery_job" if defined?(Rails)
 require "courrier/email/layouts"
+require "courrier/markdown"
 require "courrier/email/options"
 require "courrier/email/provider"
 
@@ -34,7 +37,11 @@ module Courrier
         @queue_options ||= {}
       end
 
-      attr_writer :queue_options
+      attr_writer :queue_options, :headers
+
+      def headers(**options)
+        options.empty? ? (@headers ||= {}) : @headers = options
+      end
 
       def enqueue(**options)
         self.queue_options = options
@@ -98,7 +105,8 @@ module Courrier
         api_key: @api_key,
         options: @options,
         provider_options: Courrier.configuration&.providers&.[](@provider.to_s.downcase.to_sym),
-        context_options: @context_options
+        context_options: @context_options,
+        custom_headers: self.class.headers
       ).deliver
     end
     alias_method :deliver_now, :deliver
@@ -133,7 +141,44 @@ module Courrier
       ENV["COURRIER_EMAIL_DISABLED"] == "true" || ENV["COURRIER_EMAIL_ENABLED"] == "false"
     end
 
-    def method_missing(name, *) = @context_options[name]
+    def method_missing(name, *)
+      if name == :text || name == :html
+        render_template(name.to_s).tap do |result|
+          return result || markdown_rendered if name == :html
+        end
+      else
+        @context_options[name]
+      end
+    end
+
+    def render_template(format)
+      template_path = template_file_path(format)
+
+      File.exist?(template_path) ? ERB.new(File.read(template_path)).result(binding) : nil
+    end
+
+    def render_markdown_template
+      %w[md markdown].each do |ext|
+        template_path = template_file_path(ext)
+
+        return ERB.new(File.read(template_path)).result(binding) if File.exist?(template_path)
+      end
+
+      nil
+    end
+
+    def markdown_rendered
+      return unless Courrier::Markdown.available?
+
+      markdown_content = render_markdown_template || (respond_to?(:markdown, true) ? markdown : nil)
+      Courrier::Markdown.render(markdown_content) if markdown_content
+    end
+
+    def template_file_path(format)
+      class_path = self.class.name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+
+      File.join(Courrier.configuration&.email_path, "#{class_path}.#{format}.erb")
+    end
 
     def respond_to_missing?(name, include_private = false) = true
   end

data/lib/courrier/markdown.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Markdown
+    class << self
+      def available?
+        defined?(::Redcarpet) || defined?(::Kramdown) || defined?(::Commonmarker)
+      end
+
+      def render(text)
+        return unless available?
+
+        parser.parse(text.to_s)
+      end
+
+      private
+
+      def parser
+        @parser ||= available_parser.new
+      end
+
+      def available_parser
+        return RedcarpetParser if defined?(::Redcarpet)
+        return KramdownParser if defined?(::Kramdown)
+        return CommonmarkerParser if defined?(::Commonmarker)
+
+        Parser
+      end
+    end
+
+    class Parser
+      def parse(text) = text.to_s
+    end
+
+    class RedcarpetParser < Parser
+      def parse(text)
+        renderer = Redcarpet::Render::HTML.new
+        markdown = Redcarpet::Markdown.new(renderer)
+
+        markdown.render(text)
+      end
+    end
+
+    class KramdownParser < Parser
+      def parse(text) = Kramdown::Document.new(text).to_html
+    end
+
+    class CommonmarkerParser < Parser
+      def parse(text) = Commonmarker.to_html(text)
+    end
+  end
+end

data/lib/courrier/version.rb

@@ -1,3 +1,3 @@
 module Courrier
-  VERSION = "0.8.2"
+  VERSION = "0.10.0"
 end

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

@@ -1,8 +1,6 @@
 class <%= class_name %><%= options[:skip_suffix] ? "" : "Email" %> < <%= parent_class %>
   def subject = ""
 
-  # Create HTML and text emails using:
-  # https://railsdesigner.com/minimal-email-editor/
   def text
     <<~TEXT
     TEXT

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: courrier
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Rails Designer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-20 00:00:00.000000000 Z
+date: 2026-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchy
@@ -98,6 +98,7 @@ files:
 - lib/courrier/engine.rb
 - lib/courrier/errors.rb
 - lib/courrier/jobs/email_delivery_job.rb
+- lib/courrier/markdown.rb
 - lib/courrier/railtie.rb
 - lib/courrier/subscriber.rb
 - lib/courrier/subscriber/base.rb
@@ -137,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: API-powered email delivery for Ruby apps