emailfuse 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1870b9111d8d731962de39300f68e6ac57faa8a67e4233d70eda08e32848d675
-  data.tar.gz: c0b955ed9bff041c6410d9b5ab93ba1a7292d3377630a1080a416cfb3d4d57cf
+  metadata.gz: ed5308d363064b9bea74f6d008a55bde447dc2f956689a2d357e8ce8467775b9
+  data.tar.gz: 259675d6b858aba7da91e34b31e7a199ab5f98b70b81bbc0c64b8e72c959c01f
 SHA512:
-  metadata.gz: d60b56c812cb1198f619442d9bc1758205d458734f6f3e163d385558ca12c6b294367a828189d807571e7699a60cd9a458c2afd529c7fd4c0ffec4021108c378
-  data.tar.gz: 78a748fffc10dcd1bf3959b0da4a6649e241a71b14ec6579f9d7376e261e547f67d9cfdafd9938a6f81927dde7c47e2d470043e36811b2630c6506ba4fbaa171
+  metadata.gz: eb5deeb16c7d71d1873557cbbdace95c73e3d3c913f4a157f8c55345ce3c06636d16abbbb69d5a268b461b4dbec81faa15d435db1a6e77f311f60183b4127027
+  data.tar.gz: cd86a4342f1994e0462f90537de60d36e29baea5b737fa383bd6d5cdb8bde5e943dc4910a3fd3332c4b50eeeba0c9d8132344c641bcb773373f8f319928c0bcf

data/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-10-31
+
+### Overview
+
+This major release introduces breaking changes to the Contacts API and deprecates the Audiences API in favor of Segments. **If you only use the SDK for sending emails or the Audiences API, you can upgrade to v1.0.0 without any code changes.** The breaking changes are limited to the Contacts API only.
+
+### ⚠️ BREAKING CHANGES
+
+#### Contacts API Changes
+
+- ⚠️ **Change `Contacts.create` to accept hash parameter with optional `audience_id`** - Previously required `audience_id` in params, now it's optional. Supports global contacts.
+- ⚠️ **Change `Contacts.get` from `get(audience_id, id)` to `get(params)`** - Now accepts a hash with optional `audience_id` and required `id` or `email`. Raises `ArgumentError: "Missing \`id\` or \`email\` field"` when neither is provided.
+- ⚠️ **Change `Contacts.list` from `list(audience_id, params = {})` to `list(params = {})`** - Now accepts a hash with optional `audience_id` and pagination params
+- ⚠️ **Change `Contacts.remove` from `remove(audience_id, contact_id)` to `remove(params)`** - Now accepts a hash with optional `audience_id` and required `id` or `email`. Raises `ArgumentError: "Missing \`id\` or \`email\` field"` when neither is provided.
+- ⚠️ **Change `Contacts.update` error message** - Error changed from `"id or email is required"` to `"Missing \`id\` or \`email\` field"` to match Node.js SDK format
+- ⚠️ **Change `Contacts.update` to accept optional `audience_id`** - Previously required `audience_id` in params, now it's optional
+
+**Before (v0.x):**
+
+```ruby
+# Methods used positional arguments and required audience_id
+Resend::Contacts.create(audience_id: "aud_123", email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get("aud_123", "contact_123")
+contacts = Resend::Contacts.list("aud_123")
+contacts = Resend::Contacts.list("aud_123", limit: 10)
+Resend::Contacts.update(audience_id: "aud_123", id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove("aud_123", "contact_123")
+```
+
+**After (v1.0.0):**
+
+```ruby
+# Methods use hash parameters and support optional audience_id
+# Global contacts (no audience_id)
+Resend::Contacts.create(email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get(id: "contact_123")
+contact = Resend::Contacts.get(email: "user@example.com")
+contacts = Resend::Contacts.list
+contacts = Resend::Contacts.list(limit: 10)
+Resend::Contacts.update(id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove(id: "contact_123")
+
+# Audience-scoped contacts (with audience_id)
+Resend::Contacts.create(audience_id: "aud_123", email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get(audience_id: "aud_123", id: "contact_123")
+contacts = Resend::Contacts.list(audience_id: "aud_123", limit: 10)
+Resend::Contacts.update(audience_id: "aud_123", id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove(audience_id: "aud_123", id: "contact_123")
+```
+
+#### Audiences API Deprecated
+
+- ⚠️ **Deprecate `Resend::Audiences` in favor of `Resend::Segments`** - The Audiences module has been replaced with Segments. A backward-compatible alias `Audiences = Segments` has been added, so existing code will continue to work.
+
+**Migration (Recommended):**
+
+Update your code to use `Segments` instead of `Audiences`:
+
+```ruby
+# Before (still works but deprecated)
+Resend::Audiences.create(name: "My Audience")
+Resend::Audiences.get("audience_123")
+Resend::Audiences.list
+Resend::Audiences.remove("audience_123")
+
+# After (recommended)
+Resend::Segments.create(name: "My Segment")
+Resend::Segments.get("segment_123")
+Resend::Segments.list
+Resend::Segments.remove("segment_123")
+```
+
+**Note:** The `Audiences` alias is deprecated and may be removed in a future major version. Please migrate to `Segments`.
+
+### Added
+
+#### New API Modules
+
+- Add `Resend::Templates` API for managing email templates
+  - `Templates.create` - Create a new template
+  - `Templates.get` - Retrieve a template by ID
+  - `Templates.update` - Update an existing template
+  - `Templates.publish` - Publish a template
+  - `Templates.duplicate` - Duplicate an existing template
+  - `Templates.list` - List all templates with pagination
+  - `Templates.remove` - Delete a template
+- Add `Resend::Topics` API for managing topics
+  - `Topics.create` - Create a new topic
+  - `Topics.get` - Retrieve a topic by ID
+  - `Topics.update` - Update a topic
+  - `Topics.list` - List all topics with pagination
+  - `Topics.remove` - Delete a topic
+- Add `Resend::Segments` API for managing segments (replacement for Audiences)
+  - `Segments.create` - Create a new segment
+  - `Segments.get` - Retrieve a segment by ID
+  - `Segments.list` - List all segments
+  - `Segments.remove` - Delete a segment
+- Add `Resend::ContactProperties` API for managing custom contact properties
+  - `ContactProperties.update` - Update contact properties (validates and raises `ArgumentError: "Missing \`id\` field"` when id is not provided)
+  - `ContactProperties.get` - Retrieve contact properties by ID
+- Add `Resend::Contacts::Segments` API for managing contact-segment relationships
+  - `Contacts::Segments.list` - List all segments for a contact
+  - `Contacts::Segments.add` - Add a contact to a segment
+  - `Contacts::Segments.remove` - Remove a contact from a segment
+- Add `Resend::Contacts::Topics` API for managing contact topic subscriptions
+  - `Contacts::Topics.list` - List topic subscriptions for a contact
+  - `Contacts::Topics.update` - Update topic subscriptions (opt-in/opt-out) for a contact
+
+#### Contacts API Enhancements
+
+- Add support for `email` parameter in `Contacts.get` and `Contacts.remove` methods (can now use email instead of ID)
+- Add `audience_id` support in Contacts API methods for scoped operations
+- Add support for global contacts (contacts not scoped to a specific audience/segment)
+- Add validation error messages matching Node.js SDK format with backticks around field names
+
+#### Broadcasts API Updates
+
+- Add deprecation warnings for `audience_id` in `Broadcasts.create` and `Broadcasts.update` (use `segment_id` instead)
+
+### Removed
+
+- Remove deprecated `send_email` method from `Resend::Emails` module (use `Resend::Emails.send` instead)
+
+[1.0.0]: https://github.com/resend/resend-ruby/compare/v0.26.0...v1.0.0

data/README.md

@@ -1,22 +1,103 @@
-# Emailfuse Gem
+# EmailFuse Ruby and Rails SDK
 
-An API wrapper for Emailfuse, including a Rails Action Mailer adapter.
+---
 
-## Installing
+## Installation
 
-In your `Gemfile`
+To install EmailFuse Ruby and Rails SDK, simply execute the following command in a terminal:
+
+Via RubyGems:
+
+```
+gem install emailfuse
+```
+
+Via Gemfile:
+
+```
+gem 'emailfuse'
+```
+
+## Setup
 
 ```ruby
-gem "emailfuse"
+require "emailfuse"
+EmailFuse.api_key = ENV["EMAILFUSE_API_KEY"]
+```
+
+or
+
+```ruby
+require "emailfuse"
+EmailFuse.configure do |config|
+  config.api_key = ENV["EMAILFUSE_API_KEY"]
+end
+```
+
+## Example
+
+```rb
+require "emailfuse"
+
+EmailFuse.api_key = ENV["EMAILFUSE_API_KEY"]
+
+params = {
+  "from": "onboarding@resend.dev",
+  "to": ["delivered@resend.dev", "your@email.com"],
+  "html": "<h1>Hello World</h1>",
+  "subject": "Hey"
+}
+r = EmailFuse::Emails.send(params)
+puts r
 ```
 
-## Usage
+# Rails and ActionMailer support
 
-Create an initializer file in `config/initializers/emailfuse.rb` with the following:
+This gem can be used as an ActionMailer delivery method, add this to your `config/environments/environment.rb` file.
 
 ```ruby
 config.action_mailer.delivery_method = :emailfuse
-Emailfuse.configure do |config|
-  config.token = ENV["EMAILFUSE_TOKEN"]
+```
+
+### Configuration Options
+
+You can configure the API key and host in two ways:
+
+#### Option 1: Global Configuration (Initializer)
+
+Create or update your mailer initializer file:
+
+```rb
+# /config/initializers/emailfuse.rb
+EmailFuse.configure do |config|
+  config.api_key = ENV["EMAILFUSE_API_KEY"]
+  config.base_url = "https://api.emailfuse.net"  # optional, defaults to https://api.emailfuse.net
 end
 ```
+
+#### Option 2: Rails Mailer Settings
+
+Configure directly in your environment file:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :emailfuse
+config.action_mailer.emailfuse_settings = {
+  api_key: ENV["EMAILFUSE_API_KEY"],
+  host: "https://api.emailfuse.net"  # optional
+}
+```
+
+Settings configured via `emailfuse_settings` take precedence over the global configuration, allowing you to use different credentials per environment.
+
+### Sending Emails
+
+After configuration, you can use `deliver_now!`:
+
+```ruby
+mailer = EmailMailer.email(self)
+response = mailer.deliver_now!
+
+puts response[:id]
+# => "b8f94710-0d84-429c-925a-22d3d8f86916"
+```

data/lib/email_fuse/batch.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # Module responsible for wrapping Batch email sending API
+  module Batch
+    class << self
+      # Send a batch of emails
+      #
+      # @param params [Array<Hash>] Array of email parameters (max 100 emails)
+      # @param options [Hash] Additional options for the request
+      # @option options [String] :idempotency_key Optional idempotency key
+      # @option options [String] :batch_validation Batch validation mode: "strict" (default) or "permissive"
+      #   - "strict": Entire batch fails if any email is invalid
+      #   - "permissive": Sends valid emails and returns errors for invalid ones
+      #
+      # @return [Hash] Response with :data array and optional :errors array (in permissive mode)
+      #
+      # @example Send batch with strict validation (default)
+      #   EmailFuse::Batch.send([
+      #     { from: "sender@example.com", to: ["recipient@example.com"], subject: "Hello", html: "<p>Hi</p>" }
+      #   ])
+      #
+      # @example Send batch with permissive validation
+      #   response = EmailFuse::Batch.send(emails, options: { batch_validation: "permissive" })
+      #   # response[:data] contains successful email IDs
+      #   # response[:errors] contains validation errors with index and message
+      #
+      # https://resend.com/docs/api-reference/emails/send-batch-emails
+      def send(params = [], options: {})
+        path = "emails/batch"
+
+        EmailFuse::Request.new(path, params, "post", options: options).perform
+      end
+    end
+  end
+end

data/lib/email_fuse/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# backwards compatibility
+require "email_fuse/emails"
+
+module EmailFuse
+  # Client class.
+  class Client
+    include EmailFuse::Emails
+
+    attr_reader :api_key
+
+    def initialize(api_key)
+      raise ArgumentError, "API Key is not a string" unless api_key.is_a?(String)
+
+      @api_key = api_key
+    end
+  end
+end

data/lib/email_fuse/emails/attachments.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  module Emails
+    # Module for sent email attachments API operations
+    module Attachments
+      class << self
+        # Retrieve a single attachment from a sent email
+        #
+        # @param params [Hash] Parameters for retrieving the attachment
+        # @option params [String] :id The attachment ID (required)
+        # @option params [String] :email_id The email ID (required)
+        # @return [Hash] The attachment object
+        #
+        # @example
+        #   EmailFuse::Emails::Attachments.get(
+        #     id: "2a0c9ce0-3112-4728-976e-47ddcd16a318",
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+        #   )
+        def get(params = {})
+          attachment_id = params[:id]
+          email_id = params[:email_id]
+
+          path = "emails/#{email_id}/attachments/#{attachment_id}"
+          EmailFuse::Request.new(path, {}, "get").perform
+        end
+
+        # List attachments from a sent email with optional pagination
+        #
+        # @param params [Hash] Parameters for listing attachments
+        # @option params [String] :email_id The email ID (required)
+        # @option params [Integer] :limit Maximum number of attachments to return (1-100)
+        # @option params [String] :after Cursor for pagination (newer attachments)
+        # @option params [String] :before Cursor for pagination (older attachments)
+        # @return [Hash] List of attachments with pagination info
+        #
+        # @example List all attachments
+        #   EmailFuse::Emails::Attachments.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+        #   )
+        #
+        # @example List with custom limit
+        #   EmailFuse::Emails::Attachments.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+        #     limit: 50
+        #   )
+        #
+        # @example List with pagination
+        #   EmailFuse::Emails::Attachments.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+        #     limit: 20,
+        #     after: "attachment_id_123"
+        #   )
+        def list(params = {})
+          email_id = params[:email_id]
+          base_path = "emails/#{email_id}/attachments"
+
+          # Extract pagination parameters
+          pagination_params = params.slice(:limit, :after, :before)
+
+          path = EmailFuse::PaginationHelper.build_paginated_path(base_path, pagination_params)
+          EmailFuse::Request.new(path, {}, "get").perform
+        end
+      end
+    end
+  end
+end

data/lib/email_fuse/emails/receiving/attachments.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  module Emails
+    module Receiving
+      # Module for received email attachments API operations
+      module Attachments
+        class << self
+          # Retrieve a single attachment from a received email
+          #
+          # @param params [Hash] Parameters for retrieving the attachment
+          # @option params [String] :id The attachment ID (required)
+          # @option params [String] :email_id The email ID (required)
+          # @return [Hash] The attachment object
+          #
+          # @example
+          #   EmailFuse::Emails::Receiving::Attachments.get(
+          #     id: "2a0c9ce0-3112-4728-976e-47ddcd16a318",
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+          #   )
+          def get(params = {})
+            attachment_id = params[:id]
+            email_id = params[:email_id]
+
+            path = "emails/receiving/#{email_id}/attachments/#{attachment_id}"
+            EmailFuse::Request.new(path, {}, "get").perform
+          end
+
+          # List attachments from a received email with optional pagination
+          #
+          # @param params [Hash] Parameters for listing attachments
+          # @option params [String] :email_id The email ID (required)
+          # @option params [Integer] :limit Maximum number of attachments to return (1-100)
+          # @option params [String] :after Cursor for pagination (newer attachments)
+          # @option params [String] :before Cursor for pagination (older attachments)
+          # @return [Hash] List of attachments with pagination info
+          #
+          # @example List all attachments
+          #   EmailFuse::Emails::Receiving::Attachments.list(
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+          #   )
+          #
+          # @example List with custom limit
+          #   EmailFuse::Emails::Receiving::Attachments.list(
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+          #     limit: 50
+          #   )
+          #
+          # @example List with pagination
+          #   EmailFuse::Emails::Receiving::Attachments.list(
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+          #     limit: 20,
+          #     after: "attachment_id_123"
+          #   )
+          def list(params = {})
+            email_id = params[:email_id]
+            base_path = "emails/receiving/#{email_id}/attachments"
+
+            # Extract pagination parameters
+            pagination_params = params.slice(:limit, :after, :before)
+
+            path = EmailFuse::PaginationHelper.build_paginated_path(base_path, pagination_params)
+            EmailFuse::Request.new(path, {}, "get").perform
+          end
+        end
+      end
+    end
+  end
+end

data/lib/email_fuse/emails/receiving.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  module Emails
+    # Module for receiving emails API operations
+    module Receiving
+      class << self
+        # Retrieve a single received email
+        #
+        # @param email_id [String] The ID of the received email
+        # @return [Hash] The received email object
+        #
+        # @example
+        #   EmailFuse::Emails::Receiving.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+        def get(email_id = "")
+          path = "emails/receiving/#{email_id}"
+          EmailFuse::Request.new(path, {}, "get").perform
+        end
+
+        # List received emails with optional pagination
+        #
+        # @param params [Hash] Optional parameters for pagination
+        # @option params [Integer] :limit Maximum number of emails to return (1-100)
+        # @option params [String] :after Cursor for pagination (newer emails)
+        # @option params [String] :before Cursor for pagination (older emails)
+        # @return [Hash] List of received emails with pagination info
+        #
+        # @example List all received emails
+        #   EmailFuse::Emails::Receiving.list
+        #
+        # @example List with custom limit
+        #   EmailFuse::Emails::Receiving.list(limit: 50)
+        #
+        # @example List with pagination
+        #   EmailFuse::Emails::Receiving.list(limit: 20, after: "email_id_123")
+        def list(params = {})
+          path = EmailFuse::PaginationHelper.build_paginated_path("emails/receiving", params)
+          EmailFuse::Request.new(path, {}, "get").perform
+        end
+      end
+    end
+  end
+end

data/lib/email_fuse/emails.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # Module responsible for wrapping email sending API
+  module Emails
+    class << self
+      # Sends or schedules an email.
+      # see more: https://resend.com/docs/api-reference/emails/send-email
+      def send(params, options: {})
+        path = "emails"
+        EmailFuse::Request.new(path, params, "post", options: options).perform
+      end
+
+      # Retrieve a single email.
+      # see more: https://resend.com/docs/api-reference/emails/retrieve-email
+      def get(email_id = "")
+        path = "emails/#{email_id}"
+        EmailFuse::Request.new(path, {}, "get").perform
+      end
+
+      # Update a scheduled email.
+      # see more: https://resend.com/docs/api-reference/emails/update-email
+      def update(params)
+        path = "emails/#{params[:email_id]}"
+        EmailFuse::Request.new(path, params, "patch").perform
+      end
+
+      # Cancel a scheduled email.
+      # see more: https://resend.com/docs/api-reference/emails/cancel-email
+      def cancel(email_id = "")
+        path = "emails/#{email_id}/cancel"
+        EmailFuse::Request.new(path, {}, "post").perform
+      end
+
+      # List emails with optional pagination.
+      # see more: https://resend.com/docs/api-reference/emails/list-emails
+      #
+      # @param options [Hash] Optional parameters for pagination
+      # @option options [Integer] :limit Maximum number of emails to return (1-100, default 20)
+      # @option options [String] :after Cursor for pagination (newer emails)
+      # @option options [String] :before Cursor for pagination (older emails)
+      def list(options = {})
+        path = "emails"
+
+        # Build query parameters, filtering out nil values
+        query_params = {}
+        query_params[:limit] = options[:limit] if options[:limit]
+        query_params[:after] = options[:after] if options[:after]
+        query_params[:before] = options[:before] if options[:before]
+
+        EmailFuse::Request.new(path, query_params, "get").perform
+      end
+    end
+  end
+end

data/lib/email_fuse/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # Errors wrapper class
+  # For more info: https://resend.com/docs/api-reference/error-codes
+  class Error < StandardError
+    # 4xx HTTP status code
+    ClientError = Class.new(self)
+
+    # 5xx HTTP status code
+    ServerError = Class.new(self)
+
+    # code 500
+    InternalServerError = Class.new(ServerError)
+
+    # code 422
+    InvalidRequestError = Class.new(ServerError)
+
+    # code 429
+    class RateLimitExceededError < ServerError
+      attr_reader :rate_limit_limit, :rate_limit_remaining, :rate_limit_reset, :retry_after
+
+      def initialize(msg, code = nil, headers = {})
+        super(msg, code, headers)
+        @rate_limit_limit = headers["ratelimit-limit"]&.to_i
+        @rate_limit_remaining = headers["ratelimit-remaining"]&.to_i
+        @rate_limit_reset = headers["ratelimit-reset"]&.to_i
+        @retry_after = headers["retry-after"]&.to_i
+      end
+    end
+
+    # code 404
+    NotFoundError = Class.new(ServerError)
+
+    ERRORS = {
+      401 => EmailFuse::Error::InvalidRequestError,
+      404 => EmailFuse::Error::InvalidRequestError,
+      422 => EmailFuse::Error::InvalidRequestError,
+      429 => EmailFuse::Error::RateLimitExceededError,
+      400 => EmailFuse::Error::InvalidRequestError,
+      500 => EmailFuse::Error::InternalServerError
+    }.freeze
+
+    attr_reader :headers
+
+    def initialize(msg, code = nil, headers = {})
+      super(msg)
+      @code = code
+      @headers = headers
+    end
+  end
+end