missive 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08e4bc0cf32260c7519cd0ec0ab1b6f378b6e15f658ca559d593f5e2f69a51eb'
-  data.tar.gz: bb9b7dd6e243f03b4efb6cda902d542b0b7eec9e2e24c1e725f3237a1c39cfdb
+  metadata.gz: 63e8195762299f95bdc217efcf1a81dbd8be46ec029ea90b8b4db430af37eabd
+  data.tar.gz: 94532fa3c3cd42c9086b35385773c0d2f8483dad96690b0d78523512736aa86e
 SHA512:
-  metadata.gz: 61713bf0d79f835d91a739073efeae708dde7033d2f64aab5f11b696b69483f532c4e795eae4db8d13c256f25b05afdf413d8262fa9a9e2c5062902d41efc82a
-  data.tar.gz: 9441fbb01803f621f33252a5e1be5fa9ff94fd5c20b5355bfe3a1e0ba44824512404fef1c28378f8ac549ba3f162910a52dbc3e1af478caf9d858b8be3f34257
+  metadata.gz: d365c0b22c19489e7d61d46746bec34d58834c167066f02eb71cec287e855a7e820e1eb535e066c2f871cc948338bbbd5151efac7838ca037e2455b36c4dbe07
+  data.tar.gz: d7c9d72e65bbac0b683b6f5b69b888547f7ebc5245c35b6b9f582042ad8ef524b775acaed2aa47d17dd4a2be689315c02e41570913edebf7c213b5d0dc728f6f

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## [Unreleased]
 
+- Add install generator
+- Add Postmark Bulk API implementation
+
 ## [0.0.1] - 2025-10-14
 
 - First release: base models, database structure

data/README.md

@@ -55,6 +55,12 @@ A lightweight Rails toolkit for building newsletter features. Missive provides t
 bundle add missive
 ```
 
+Install the migrations:
+
+```bash
+rails generate missive:install
+```
+
 ### Configuration
 
 Missive uses the same configuration as `postmark-rails`. Please follow the [`postmark-rails` configuration instructions](https://github.com/ActiveCampaign/postmark-rails?tab=readme-ov-file#installation) to set up your Postmark API credentials.
@@ -180,6 +186,68 @@ list.create_message!(subject: "Hello world!")
 message.send!
 ```
 
+### Sending with Postmark Bulk API
+
+Missive leverages the [Bulk Email API](https://postmarkapp.com/developer/api/bulk-email) endpoints.
+
+> [!WARNING]
+> This endpoint is available to early access customers only. You need to request access. [Learn more](https://postmarkapp.com/support/article/1311-the-early-access-program-for-the-new-bulk-api)
+
+The official [postmark gem](https://github.com/ActiveCampaign/postmark-gem) does not support these endpoints yet, so Missive ships with `Stamp`, a thin layer over Postmark's official library.
+
+#### Sending a message in bulk
+
+You can pass a Hash that matches the body expected by the API.
+
+```rb
+Missive::Stamp::ApiClient.deliver_in_bulk(
+  from: "sender@example.com",
+  subject: "Hello {{name}}",
+  html_body: "<p>Hello {{name}}</p>",
+  text_body: "Hello {{name}}",
+  messages: [
+    {
+      to: "jane.doe@example.com",
+      template_model: {name: "Jane"}
+    },
+    {
+      to: "john.doe@example.com",
+      template_model: {name: "John"}
+    }
+  ]
+)
+```
+
+You can also pass a `Mail` instance and an Array of recipients.
+
+```rb
+mail = Mail.new do
+  from "sender@example.com"
+  subject "Hello {{name}}"
+  body: "Hello {{name}}"
+end
+
+Missive::Stamp::ApiClient.deliver_message_in_bulk(
+  mail,
+  [
+    {
+      to: "jane.doe@example.com",
+      template_model: {name: "Jane"}
+    },
+    {
+      to: "john.doe@example.com",
+      template_model: {name: "John"}
+    }
+  ]
+)
+```
+
+#### Getting the status of a bulk API request
+
+```rb
+Missive::Stamp::ApiClient.get_bulk_status("f24af63c-533d-4b7a-ad65-4a7b3202d3a7")
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/missive/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module Missive
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_missive_migrations
+        migration_template "migrations/install_missive.rb.erb", "db/migrate/install_missive.rb"
+      end
+
+      private
+
+      def migration_class_name
+        if Rails::VERSION::MAJOR >= 5
+          "ActiveRecord::Migration[#{ActiveRecord::Migration.current_version}]"
+        else
+          "ActiveRecord::Migration"
+        end
+      end
+    end
+  end
+end

data/lib/generators/missive/templates/migrations/install_missive.rb.erb

@@ -0,0 +1,74 @@
+class InstallMissive < <%= migration_class_name %>
+  def change
+    create_table :missive_subscribers do |t|
+      t.string :email, null: false
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+      t.references :user, foreign_key: true
+
+      t.timestamps
+    end
+
+    create_table :missive_lists do |t|
+      t.string :name, null: false
+      t.integer :subscriptions_count, default: 0
+      t.integer :messages_count, default: 0
+      t.timestamp :last_message_sent_at
+      t.string :postmark_message_stream_id
+
+      t.timestamps
+    end
+
+    create_table :missive_messages do |t|
+      t.string :subject, null: false
+      t.integer :dispatches_count, default: 0
+      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
+      t.string :postmark_message_stream_id
+      t.timestamp :sent_at
+
+      t.timestamps
+    end
+
+    create_table :missive_dispatches do |t|
+      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
+      t.references :message, null: false, foreign_key: {to_table: "missive_messages"}
+      t.string :postmark_message_stream_id
+      t.string :postmark_message_id
+      t.timestamp :sent_at
+      t.timestamp :delivered_at
+      t.timestamp :opened_at
+      t.timestamp :clicked_at
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+
+      t.index [:subscriber_id, :message_id], unique: true
+
+      t.timestamps
+    end
+
+    create_table :missive_subscriptions do |t|
+      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
+      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+
+      t.index [:subscriber_id, :list_id], unique: true
+
+      t.timestamps
+    end
+
+    create_table :missive_senders do |t|
+      t.string :email, null: false
+      t.string :name
+      t.string :reply_to_email
+      t.integer :postmark_sender_signature_id
+      t.references :user, foreign_key: false
+
+      t.timestamps
+    end
+
+    add_reference :missive_dispatches, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+    add_reference :missive_lists, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+    add_reference :missive_messages, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+  end
+end

data/lib/missive/stamp/api_client.rb

@@ -0,0 +1,40 @@
+module Missive
+  # Stamp is a thin layer over Postmark's official library,
+  # that improves it for Missive's needs.
+  #
+  # Main features:
+  # - implementation of the [Bulk API](https://postmarkapp.com/developer/api/bulk-email)
+  module Stamp
+    class ApiClient < ::Postmark::ApiClient
+      # Send bulk emails, passing a hash
+      # https://postmarkapp.com/developer/api/bulk-email#send-bulk-emails
+      def deliver_in_bulk(message_hash)
+        data = serialize(::Postmark::MessageHelper.to_postmark(message_hash))
+
+        with_retries do
+          format_response http_client.post("email/bulk", data)
+        end
+      end
+
+      # Send bulk emails, passing a message and its recipients
+      # https://postmarkapp.com/developer/api/bulk-email#send-bulk-emails
+      def deliver_message_in_bulk(message, recipients = [])
+        data = serialize(message.to_postmark_hash.merge(messages: recipients))
+
+        with_retries do
+          response, error = take_response_of { http_client.post("email/bulk", data) }
+          update_message(message, response)
+          raise error if error
+
+          format_response(response, compatible: true)
+        end
+      end
+
+      # Get the status/details of a bulk API request
+      # https://postmarkapp.com/developer/api/bulk-email#get-a-bulk-send-status
+      def get_bulk_status(id)
+        format_response http_client.get("email/bulk/#{id}")
+      end
+    end
+  end
+end

data/lib/missive/version.rb

@@ -1,3 +1,3 @@
 module Missive
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.2".freeze
 end

data/lib/missive.rb

@@ -1,5 +1,7 @@
 require "missive/version"
 require "missive/engine"
+require "postmark"
+require "missive/stamp/api_client"
 
 module Missive
   # Your code goes here...

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: missive
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Hans Lemuet
@@ -100,16 +100,13 @@ files:
 - app/models/missive/subscription.rb
 - app/views/layouts/missive/application.html.erb
 - config/routes.rb
-- db/migrate/20251002000005_create_missive_subscribers.rb
-- db/migrate/20251004191513_create_missive_lists.rb
-- db/migrate/20251004193630_create_missive_messages.rb
-- db/migrate/20251004201105_create_missive_dispatches.rb
-- db/migrate/20251006214059_create_missive_subscriptions.rb
-- db/migrate/20251013205354_create_missive_senders.rb
 - lefthook.yml
+- lib/generators/missive/install_generator.rb
+- lib/generators/missive/templates/migrations/install_missive.rb.erb
 - lib/missive.rb
 - lib/missive/engine.rb
 - lib/missive/railtie.rb
+- lib/missive/stamp/api_client.rb
 - lib/missive/version.rb
 - lib/tasks/missive_tasks.rake
 homepage: https://github.com/Spone/missive
@@ -133,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Toolbox for managing newsletters in Rails, sending them with Postmark.
 test_files: []

data/db/migrate/20251002000005_create_missive_subscribers.rb

@@ -1,12 +0,0 @@
-class CreateMissiveSubscribers < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_subscribers do |t|
-      t.string :email, null: false
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-      t.references :user, foreign_key: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004191513_create_missive_lists.rb

@@ -1,13 +0,0 @@
-class CreateMissiveLists < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_lists do |t|
-      t.string :name, null: false
-      t.integer :subscriptions_count, default: 0
-      t.integer :messages_count, default: 0
-      t.timestamp :last_message_sent_at
-      t.string :postmark_message_stream_id
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004193630_create_missive_messages.rb

@@ -1,13 +0,0 @@
-class CreateMissiveMessages < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_messages do |t|
-      t.string :subject, null: false
-      t.integer :dispatches_count, default: 0
-      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
-      t.string :postmark_message_stream_id
-      t.timestamp :sent_at
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004201105_create_missive_dispatches.rb

@@ -1,20 +0,0 @@
-class CreateMissiveDispatches < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_dispatches do |t|
-      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
-      t.references :message, null: false, foreign_key: {to_table: "missive_messages"}
-      t.string :postmark_message_stream_id
-      t.string :postmark_message_id
-      t.timestamp :sent_at
-      t.timestamp :delivered_at
-      t.timestamp :opened_at
-      t.timestamp :clicked_at
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-
-      t.index [:subscriber_id, :message_id], unique: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251006214059_create_missive_subscriptions.rb

@@ -1,14 +0,0 @@
-class CreateMissiveSubscriptions < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_subscriptions do |t|
-      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
-      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-
-      t.index [:subscriber_id, :list_id], unique: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251013205354_create_missive_senders.rb

@@ -1,17 +0,0 @@
-class CreateMissiveSenders < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_senders do |t|
-      t.string :email, null: false
-      t.string :name
-      t.string :reply_to_email
-      t.integer :postmark_sender_signature_id
-      t.references :user, foreign_key: false
-
-      t.timestamps
-    end
-
-    add_reference :missive_dispatches, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-    add_reference :missive_lists, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-    add_reference :missive_messages, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-  end
-end