courrier 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 394bb78e24569d93855f2bcf788662ec8773371779b7743c5737867b893d4b38
-  data.tar.gz: 4f35baf4f3ccca75ac05cd6bc7140f2eb4585c0c95e528f1aa45bc1227ec3777
+  metadata.gz: b2da5fe5fc7bb657449ed12d90c8443d6fa692339f9974fcbda7c4c726964ad8
+  data.tar.gz: ad4fc570a0bdb7cb1bce3c214a21e550a725212e0f900e5d31fe1345d5c7b221
 SHA512:
-  metadata.gz: 387e9a879abac10ecbd97ac1a254fb08c40e48e8faf1a37f3a284dd2efd118dd70e0bf1d0032d3318914b2ddaa9242a56495547c6599dc3483844b3449114846
-  data.tar.gz: f5b458d0cc5ff6f640f0e3ffc19be8e0e6982721dcd4ff29a3dc49d42e7a3d6e9e6b0ba2d132e8f75d2a6c5edb8f6d2ae581b3076027fc9a5a48207c54ecc2ec
+  metadata.gz: 7170f0e34c59ceee7b88c41865da67f558357058651a9508578adb5b0fec0d5da78bea1672aed8b24335128822784c1e5b23478804fb1a08273efece5129ae3f
+  data.tar.gz: 89de9523761715879b487d62ca63576eb9783647a0e2d8baba5ef268b36c91d359d96c33386b06a3cd686af8e747cf548eaf74ea9654efde22030a52eaac5fe4

data/Gemfile.lock

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

data/README.md

@@ -2,6 +2,8 @@
 
 Modern, API-powered email delivery 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)
+
 ```ruby
 # Quick example
 OrderEmail.deliver to: "recipient@railsdesigner.com"
@@ -39,6 +41,7 @@ Generate a new email:
 ```bash
 bin/rails generate courrier:email Order
 ```
+
 ```ruby
 class OrderEmail < Courrier::Email
   def subject = "Here is your order!"
@@ -55,7 +58,10 @@ class OrderEmail < Courrier::Email
     HTML
   end
 end
+
+# OrderEmail.deliver to: "recipient@railsdesigner.com"
 ```
+
 💡 Write your email content using the [Minimal Email Editor](https://railsdesigner.com/minimal-email-editor/).
 
 
@@ -80,7 +86,7 @@ end
 2. **Email class defaults**
 ```ruby
 class OrderEmail < Courrier::Email
-  configure from: "devs@railsdesigner.com",
+  configure from: "orders@railsdesigner.com",
             cc: "records@railsdesigner.com",
             provider: "mailgun",
 end
@@ -89,12 +95,61 @@ end
 3. **Instance options**
 ```ruby
 OrderEmail.deliver to: "recipient@railsdesigner.com",\
-                   from: "devs@railsdesigner.com",\
+                   from: "shop@railsdesigner.com",\
                    provider: "sendgrid",\
                    api_key: "sk_a1b1c3"
 ```
 
 
+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
+
+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")
+```
+
+These custom attributes are accessible directly in your email class:
+```ruby
+def text
+  <<~TEXT
+    #{download_url}
+  TEXT
+end
+```
+
+
+## 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
+
+| Method | Return Type | Description |
+|:-------|:-----------|:------------|
+| `success?` | Boolean | Returns `true` if the API request was successful |
+| `response` | Net::HTTP::Response | The raw HTTP response from the email provider |
+| `data` | Hash | Parsed JSON response body from the provider |
+| `error` | Exception | Contains any error that occurred during delivery |
+
+
+### Example
+
+```ruby
+delivery = OrderEmail.deliver(to: "recipient@example.com")
+
+if delivery.success?
+  puts "Email sent successfully!"
+  puts "Provider response: #{delivery.data}"
+else
+  puts "Failed to send email: #{delivery.error}"
+end
+```
+
+
 ## Providers
 
 Courrier supports these transactional email providers:
@@ -106,6 +161,7 @@ Courrier supports these transactional email providers:
 - [Postmark](https://postmarkapp.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). 🙏
 
@@ -119,10 +175,10 @@ Additional functionality to help with development and email handling:
 
 Preview emails in your browser during development:
 ```ruby
-
config.provider = "preview" # Opens emails in your default browser
+
config.provider = "preview" # Opens emails in your default browser
 ```
 
-
Previews are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
+
Previews are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
 
 
 ### Layout Support
@@ -172,13 +228,13 @@ end
 
 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
 
-Compose RFC 2822-compliant email addresses with display names:
+Compose email addresses with display names:
 ```ruby
 class SignupsController < ApplicationController
   def create
@@ -214,9 +270,9 @@ config.logger = custom_logger # Optional: defaults to ::Logger.new($stdout)
 
 ### Custom Providers
 
-Create your own provider by inheriting from `Courrier::Email::Base`:
+Create your own provider by inheriting from `Courrier::Email::Providers::Base`:
 ```ruby
-class CustomProvider < Courrier::Email::Base
+class CustomProvider < Courrier::Email::Providers::Base
   ENDPOINT_URL = ""
 
   def body = ""

data/lib/courrier/configuration/preview.rb

@@ -14,9 +14,7 @@ module Courrier
       private
 
       def default_destination
-        return Rails.root.join("tmp", "courrier", "emails").to_s if defined?(Rails)
-
-        File.join(Dir.tmpdir, "courrier", "emails")
+        defined?(Rails) ? Rails.root.join("tmp", "courrier", "emails").to_s : File.join(Dir.tmpdir, "courrier", "emails")
       end
     end
   end

data/lib/courrier/configuration.rb

@@ -45,9 +45,7 @@ module Courrier
     private
 
     def default_email_path
-      return Rails.root.join("app", "emails").to_s if defined?(Rails)
-
-      File.join("courrier", "emails")
+      defined?(Rails) ? Rails.root.join("app", "emails").to_s : File.join("courrier", "emails")
     end
   end
 end

data/lib/courrier/email/provider.rb

@@ -10,6 +10,7 @@ require "courrier/email/providers/postmark"
 require "courrier/email/providers/preview"
 require "courrier/email/providers/sendgrid"
 require "courrier/email/providers/sparkpost"
+require "courrier/email/providers/userlist"
 
 module Courrier
   class Email
@@ -43,7 +44,8 @@ module Courrier
         postmark: Courrier::Email::Providers::Postmark,
         preview: Courrier::Email::Providers::Preview,
         sendgrid: Courrier::Email::Providers::Sendgrid,
-        sparkpost: Courrier::Email::Providers::Sparkpost
+        sparkpost: Courrier::Email::Providers::Sparkpost,
+        userlist: Courrier::Email::Providers::Userlist
       }.freeze
 
       def configuration_missing_in_production?

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

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

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Email
+    module Providers
+      class Userlist < Base
+        ENDPOINT_URL = "https://push.userlist.com/messages"
+
+        def body
+          {
+            "from" => @options.from,
+            "to" => @options.to,
+            "subject" => @options.subject,
+            "body" => body_document
+          }.compact.merge(provider_options)
+        end
+
+        private
+
+        def headers
+          {
+            "Authorization" => "Push #{@api_key}"
+          }
+        end
+
+        def body_document
+          if @options.html && @options.text
+            multipart_document
+          elsif @options.html
+            html_document
+          elsif @options.text
+            text_document
+          end
+        end
+
+        def text_document
+          {
+            "type" => "text",
+            "content" => @options.text
+          }
+        end
+
+        def html_document
+          {
+            "type" => "html",
+            "content" => @options.html
+          }
+        end
+
+        def multipart_document
+          {
+            "type" => "multipart",
+            "content" => [
+              html_document,
+              text_document
+            ]
+          }
+        end
+
+        def provider_options
+          {"theme" => nil}.merge(@provider_options)
+        end
+      end
+    end
+  end
+end

data/lib/courrier/email/request.rb

@@ -42,11 +42,9 @@ module Courrier
       end
 
       def body_for(request)
-        if requires_multipart_form?
-          set_multipart_form(request)
-        else
-          set_json_body(request)
-        end
+        return set_multipart_form(request) if requires_multipart_form?
+
+        set_json_body(request)
       end
 
       def default_headers

data/lib/courrier/email.rb

@@ -49,7 +49,7 @@ module Courrier
 
     def initialize(options = {})
       @provider = options[:provider] || ENV["COURRIER_PROVIDER"] || self.class.provider || Courrier.configuration&.provider
-      @api_key = options[:api_key] || ENV["COURRIER_PROVIDER"] || self.class.api_key || Courrier.configuration&.api_key
+      @api_key = options[:api_key] || ENV["COURRIER_API_KEY"] || self.class.api_key || Courrier.configuration&.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)
@@ -79,7 +79,7 @@ module Courrier
         provider: @provider,
         api_key: @api_key,
         options: @options,
-        provider_options: Courrier.configuration&.providers&.[](@provider.to_s.downcase.to_sym)&.to_h
+        provider_options: Courrier.configuration&.providers&.[](@provider.to_s.downcase.to_sym)
       ).deliver
     end
     alias_method :deliver_now, :deliver

data/lib/courrier/version.rb

@@ -1,3 +1,3 @@
 module Courrier
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: courrier
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Rails Designer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-09 00:00:00.000000000 Z
+date: 2025-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchy
@@ -86,6 +86,7 @@ files:
 - lib/courrier/email/providers/preview/default.html.erb
 - lib/courrier/email/providers/sendgrid.rb
 - lib/courrier/email/providers/sparkpost.rb
+- lib/courrier/email/providers/userlist.rb
 - lib/courrier/email/request.rb
 - lib/courrier/email/result.rb
 - lib/courrier/email/transformer.rb