courrier 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3d93b4337d15e066ffa7ed4626dd254231ee744940de07b7b76be8714afbde
-  data.tar.gz: d7ef7a3ed1a8600581b6bdf13f63072c49ad138ad52384e1c358dbcd8f8a45b2
+  metadata.gz: 555584763bab84eb75f07a5a7fa43fb4e4a65c3b1bb52de2c8e551c744fd0625
+  data.tar.gz: 4901dfab5c8c70d2f741e6c5edc0014e2aa7a9ca4afddc011d0d946464da709d
 SHA512:
-  metadata.gz: 32d2fba728012eb703ca67044484a2f0caf0177ee0f341b6973566a50136f6531dfc37edfe7347511b4de67291af0364f6f03ad4c22247f5bbd72ca306e13455
-  data.tar.gz: 5a3ea2ea5fb0637f025a3577d6e1004a66478e0929b96752b0fdea302af95f6c88af3bed801265dc14f6645a8014adb781cd1cc04ee1809bedf76ca892f4c4f0
+  metadata.gz: 93d5a592840d197493eafc3b8cac47b03218b9d8bdce88ef2e666685468a32879583ea7bb7adc1e84a665864ee5d4aebc80e982606f78836d2cf996e7fd5e602
+  data.tar.gz: d2e4391d1ea6d24031fbba9539f4935386b552184e145a4a2582e0a9a72003d3f79ed2afc6091ca9b2f4069b725e8a778602b8d31fe688999fad2badc4535276

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    courrier (0.9.0)
+    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:
@@ -289,6 +304,53 @@ 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:
@@ -447,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,13 +30,14 @@ 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
@@ -47,7 +48,8 @@ module Courrier
           api_key: @api_key,
           options: @options,
           provider_options: @provider_options,
-          context_options: @context_options
+          context_options: @context_options,
+          custom_headers: @custom_headers
         ).deliver
       end
 

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

@@ -5,6 +5,7 @@ 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"
 
@@ -36,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
@@ -100,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
@@ -137,7 +143,9 @@ module Courrier
 
     def method_missing(name, *)
       if name == :text || name == :html
-        render_template(name.to_s)
+        render_template(name.to_s).tap do |result|
+          return result || markdown_rendered if name == :html
+        end
       else
         @context_options[name]
       end
@@ -149,6 +157,23 @@ module Courrier
       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
 

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.9.0"
+  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.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Rails Designer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-04 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