resend 0.27.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d14aa64ac124d647f4fb79b7f408e485fb91c67289a6e085fe39bca75e602793
-  data.tar.gz: c4302a083a1b6c2ed08ae62825ea1383ee53644967b59e9279d6489863dfdbdd
+  metadata.gz: 67dadb5f7acb77801501030612149bf52b6c46626fd5630a233a77ab6fc552d7
+  data.tar.gz: 8842020484f59a566282b8ff1258bfeea02594274b2f117c548ae2ad49284ad2
 SHA512:
-  metadata.gz: e1d6b730a10d67e4643d11b24ab11c9c26007ef874505fa0afd569009e16449c073c978a82d734f108f3f71660762b7591c3c8b95f2fabd15574622b30ff80b7
-  data.tar.gz: 8f0bab76e49b940813ce73dc71daebe1a3a3f423d27b4fecfb89db06460949f80c15da300a1d5d82c4768006ba0bff0e7b641b5a0360830751f413932ae886e8
+  metadata.gz: d889989325170107795bed29b590b45382909a8b4812381c4fa330e8c94c6cf7d8c3be1474793c0b6a93c85fc3f0647fd868f5b540902cd9e6ca260821f3b5ec
+  data.tar.gz: 48ec677afd58504f02b4099fb1f4d926defa2aa64f05cb2d8e8e1c724b08f1d1b3950f79535ac89481a8f58f1b1884962c4e46247bbdb6b03e0364325822fab9

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/lib/resend/broadcasts.rb

@@ -5,13 +5,26 @@ module Resend
   module Broadcasts
     class << self
       # https://resend.com/docs/api-reference/broadcasts/create-broadcast
+      # @note Supports both segment_id and audience_id. At least one is required.
+      #   audience_id is deprecated - use segment_id instead.
+      # @note When send: true is passed, the broadcast is sent immediately instead of
+      #   creating a draft. When using send: true, you can also include scheduled_at
+      #   to schedule the broadcast. Passing scheduled_at without send: true is an error.
       def create(params = {})
+        if params[:audience_id] && !params[:segment_id]
+          warn "[DEPRECATION] Using audience_id in broadcasts is deprecated. Use segment_id instead."
+        end
         path = "broadcasts"
         Resend::Request.new(path, params, "post").perform
       end
 
       # https://resend.com/docs/api-reference/broadcasts/update-broadcast
+      # @note Supports both segment_id and audience_id. At least one may be required.
+      #   audience_id is deprecated - use segment_id instead.
       def update(params = {})
+        if params[:audience_id] && !params[:segment_id]
+          warn "[DEPRECATION] Using audience_id in broadcasts is deprecated. Use segment_id instead."
+        end
         path = "broadcasts/#{params[:broadcast_id]}"
         Resend::Request.new(path, params, "patch").perform
       end

data/lib/resend/contact_properties.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Resend
+  # Module for managing contact properties
+  #
+  # Contact properties allow you to store custom data about your contacts
+  module ContactProperties
+    class << self
+      # Create a custom property for your contacts
+      #
+      # @param params [Hash] Parameters for creating a contact property
+      # @option params [String] :key The property key (max 50 characters, alphanumeric and underscores only) (required)
+      # @option params [String] :type The property type ('string' or 'number') (required)
+      # @option params [String, Integer] :fallback_value The default value when property is not set (must match type)
+      #
+      # @return [Hash] Response containing the created contact property
+      #
+      # @example Create a string property
+      #   Resend::ContactProperties.create({
+      #     key: 'company_name',
+      #     type: 'string',
+      #     fallback_value: 'Acme Corp'
+      #   })
+      #
+      # @example Create a number property
+      #   Resend::ContactProperties.create({
+      #     key: 'age',
+      #     type: 'number',
+      #     fallback_value: 0
+      #   })
+      def create(params)
+        path = "contact-properties"
+        Resend::Request.new(path, params, "post").perform
+      end
+
+      # Retrieve a contact property by its ID
+      #
+      # @param contact_property_id [String] The Contact Property ID
+      #
+      # @return [Hash] Response containing the contact property details
+      #
+      # @example Get a contact property
+      #   Resend::ContactProperties.get('b6d24b8e-af0b-4c3c-be0c-359bbd97381e')
+      def get(contact_property_id = "")
+        path = "contact-properties/#{contact_property_id}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # Retrieve a list of contact properties
+      #
+      # @param params [Hash] Optional query parameters
+      # @option params [Integer] :limit Number of contact properties to retrieve (1-100, default: 20)
+      # @option params [String] :after The ID after which to retrieve more contact properties
+      # @option params [String] :before The ID before which to retrieve more contact properties
+      #
+      # @return [Hash] Response containing list of contact properties
+      #
+      # @example List all contact properties
+      #   Resend::ContactProperties.list
+      #
+      # @example List with pagination
+      #   Resend::ContactProperties.list({ limit: 10, after: 'cursor_123' })
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("contact-properties", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # Update an existing contact property
+      #
+      # Note: The 'key' and 'type' fields cannot be changed after creation
+      #
+      # @param params [Hash] Parameters for updating a contact property
+      # @option params [String] :id The Contact Property ID (required)
+      # @option params [String, Integer] :fallback_value The default value when property is not set
+      #   (must match property type)
+      #
+      # @return [Hash] Response containing the updated contact property
+      #
+      # @example Update fallback value
+      #   Resend::ContactProperties.update({
+      #     id: 'b6d24b8e-af0b-4c3c-be0c-359bbd97381e',
+      #     fallback_value: 'Example Company'
+      #   })
+      def update(params)
+        raise ArgumentError, "Missing `id` field" if params[:id].nil?
+
+        contact_property_id = params[:id]
+        path = "contact-properties/#{contact_property_id}"
+        Resend::Request.new(path, params, "patch").perform
+      end
+
+      # Remove an existing contact property
+      #
+      # @param contact_property_id [String] The Contact Property ID
+      #
+      # @return [Hash] Response containing the deleted property ID and confirmation
+      #
+      # @example Delete a contact property
+      #   Resend::ContactProperties.remove('b6d24b8e-af0b-4c3c-be0c-359bbd97381e')
+      def remove(contact_property_id = "")
+        path = "contact-properties/#{contact_property_id}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+    end
+  end
+end

data/lib/resend/contacts/segments.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Resend
+  module Contacts
+    # Contact Segments api wrapper
+    module Segments
+      class << self
+        #
+        # List all segments for a contact
+        #
+        # @param params [Hash] the parameters
+        # @option params [String] :contact_id the contact id (either contact_id or email is required)
+        # @option params [String] :email the contact email (either contact_id or email is required)
+        # @option params [Integer] :limit the maximum number of results to return (optional)
+        # @option params [String] :after the cursor for pagination (optional)
+        # @option params [String] :before the cursor for pagination (optional)
+        #
+        # https://resend.com/docs/api-reference/contacts/list-contact-segments
+        def list(params)
+          raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
+
+          identifier = params[:contact_id] || params[:email]
+          base_path = "contacts/#{identifier}/segments"
+          path = Resend::PaginationHelper.build_paginated_path(base_path, params)
+          Resend::Request.new(path, {}, "get").perform
+        end
+
+        #
+        # Add a contact to a segment
+        #
+        # @param params [Hash] the parameters
+        # @option params [String] :contact_id the contact id (either contact_id or email is required)
+        # @option params [String] :email the contact email (either contact_id or email is required)
+        # @option params [String] :segment_id the segment id (required)
+        #
+        # https://resend.com/docs/api-reference/contacts/add-contact-to-segment
+        def add(params)
+          raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
+          raise ArgumentError, "segment_id is required" if params[:segment_id].nil?
+
+          identifier = params[:contact_id] || params[:email]
+          path = "contacts/#{identifier}/segments/#{params[:segment_id]}"
+          Resend::Request.new(path, {}, "post").perform
+        end
+
+        #
+        # Remove a contact from a segment
+        #
+        # @param params [Hash] the parameters
+        # @option params [String] :contact_id the contact id (either contact_id or email is required)
+        # @option params [String] :email the contact email (either contact_id or email is required)
+        # @option params [String] :segment_id the segment id (required)
+        #
+        # https://resend.com/docs/api-reference/contacts/remove-contact-from-segment
+        def remove(params)
+          raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
+          raise ArgumentError, "segment_id is required" if params[:segment_id].nil?
+
+          identifier = params[:contact_id] || params[:email]
+          path = "contacts/#{identifier}/segments/#{params[:segment_id]}"
+          Resend::Request.new(path, {}, "delete").perform
+        end
+      end
+    end
+  end
+end

data/lib/resend/contacts/topics.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Resend
+  module Contacts
+    # Module for managing contact topic subscriptions
+    #
+    # Allows you to manage which topics contacts are subscribed to
+    module Topics
+      class << self
+        # Retrieve a list of topics subscriptions for a contact
+        #
+        # @param params [Hash] Parameters for listing topics
+        # @option params [String] :id The Contact ID (either :id or :email must be provided)
+        # @option params [String] :email The Contact Email (either :id or :email must be provided)
+        # @option params [Integer] :limit Number of topics to retrieve (1-100)
+        # @option params [String] :after The ID after which to retrieve more topics
+        # @option params [String] :before The ID before which to retrieve more topics
+        #
+        # @return [Hash] Response containing list of topics with subscription status
+        #
+        # @example List topics by contact ID
+        #   Resend::Contacts::Topics.list(id: 'e169aa45-1ecf-4183-9955-b1499d5701d3')
+        #
+        # @example List topics by contact email
+        #   Resend::Contacts::Topics.list(email: 'steve.wozniak@gmail.com')
+        #
+        # @example List topics with pagination
+        #   Resend::Contacts::Topics.list(id: 'contact-id', limit: 10, after: 'cursor_123')
+        def list(params = {})
+          contact_identifier = params[:id] || params[:email]
+          raise ArgumentError, "Either :id or :email must be provided" if contact_identifier.nil?
+
+          pagination_params = params.slice(:limit, :after, :before)
+          base_path = "contacts/#{contact_identifier}/topics"
+          path = Resend::PaginationHelper.build_paginated_path(base_path, pagination_params)
+
+          Resend::Request.new(path, {}, "get").perform
+        end
+
+        # Update topic subscriptions for a contact
+        #
+        # @param params [Hash] Parameters for updating topics
+        # @option params [String] :id The Contact ID (either :id or :email must be provided)
+        # @option params [String] :email The Contact Email (either :id or :email must be provided)
+        # @option params [Array<Hash>] :topics Array of topic subscription updates
+        #   Each topic hash should contain:
+        #   - :id [String] The Topic ID (required)
+        #   - :subscription [String] The subscription action: 'opt_in' or 'opt_out' (required)
+        #
+        # @return [Hash] Response containing the contact ID
+        #
+        # @example Update by contact ID
+        #   Resend::Contacts::Topics.update({
+        #     id: 'e169aa45-1ecf-4183-9955-b1499d5701d3',
+        #     topics: [
+        #       { id: 'b6d24b8e-af0b-4c3c-be0c-359bbd97381e', subscription: 'opt_out' },
+        #       { id: '07d84122-7224-4881-9c31-1c048e204602', subscription: 'opt_in' }
+        #     ]
+        #   })
+        #
+        # @example Update by contact email
+        #   Resend::Contacts::Topics.update({
+        #     email: 'steve.wozniak@gmail.com',
+        #     topics: [
+        #       { id: '07d84122-7224-4881-9c31-1c048e204602', subscription: 'opt_out' }
+        #     ]
+        #   })
+        def update(params)
+          contact_identifier = params[:id] || params[:email]
+          raise ArgumentError, "Either :id or :email must be provided" if contact_identifier.nil?
+
+          path = "contacts/#{contact_identifier}/topics"
+          body = params[:topics]
+
+          Resend::Request.new(path, body, "patch").perform
+        end
+      end
+    end
+  end
+end

data/lib/resend/contacts.rb

@@ -6,42 +6,96 @@ module Resend
     class << self
       # https://resend.com/docs/api-reference/contacts/create-contact
       def create(params)
-        path = "audiences/#{params[:audience_id]}/contacts"
-        Resend::Request.new(path, params, "post").perform
+        if params[:audience_id]
+          path = "audiences/#{params[:audience_id]}/contacts"
+          # Audience-scoped contacts don't support properties
+          payload = params.reject { |key, _| key == :properties }
+        else
+          path = "contacts"
+          payload = params
+        end
+        Resend::Request.new(path, payload, "post").perform
       end
 
       #
-      # Retrieves a contact from an audience
+      # Retrieves a contact
       #
-      # @param audience_id [String] the audience id
-      # @param id [String] either the contact id or contact's email
+      # @param params [Hash] the parameters
+      # @option params [String] :id either the contact id or contact's email (required)
+      # @option params [String] :audience_id optional audience id to scope the operation
+      #
+      # @example Get contact by ID
+      #   Resend::Contacts.get(id: "contact_123")
+      #
+      # @example Get contact scoped to an audience
+      #   Resend::Contacts.get(id: "contact_123", audience_id: "aud_456")
       #
       # https://resend.com/docs/api-reference/contacts/get-contact
-      def get(audience_id, id)
-        path = "audiences/#{audience_id}/contacts/#{id}"
+      def get(params = {})
+        raise ArgumentError, "Missing `id` or `email` field" if params[:id].nil? && params[:email].nil?
+
+        audience_id = params[:audience_id]
+        contact_id = params[:id] || params[:email]
+        path = if audience_id
+                 "audiences/#{audience_id}/contacts/#{contact_id}"
+               else
+                 "contacts/#{contact_id}"
+               end
         Resend::Request.new(path, {}, "get").perform
       end
 
       #
-      # List contacts in an audience
+      # List contacts
+      #
+      # @param params [Hash] optional parameters including pagination
+      # @option params [String] :audience_id optional audience id to scope the operation
+      # @option params [Integer] :limit number of records to return
+      # @option params [String] :cursor pagination cursor
+      #
+      # @example List all contacts
+      #   Resend::Contacts.list
+      #
+      # @example List contacts with pagination
+      #   Resend::Contacts.list(limit: 10)
+      #
+      # @example List contacts scoped to an audience
+      #   Resend::Contacts.list(audience_id: "aud_456", limit: 10)
       #
-      # @param audience_id [String] the audience id
-      # @param params [Hash] optional pagination parameters
       # https://resend.com/docs/api-reference/contacts/list-contacts
-      def list(audience_id, params = {})
-        path = Resend::PaginationHelper.build_paginated_path("audiences/#{audience_id}/contacts", params)
+      def list(params = {})
+        audience_id = params[:audience_id]
+        path = if audience_id
+                 Resend::PaginationHelper.build_paginated_path("audiences/#{audience_id}/contacts", params)
+               else
+                 Resend::PaginationHelper.build_paginated_path("contacts", params)
+               end
         Resend::Request.new(path, {}, "get").perform
       end
 
       #
-      # Remove a contact from an audience
+      # Remove a contact
+      #
+      # @param params [Hash] the parameters
+      # @option params [String] :id either the contact id or contact email (required)
+      # @option params [String] :audience_id optional audience id to scope the operation
       #
-      # @param audience_id [String] the audience id
-      # @param contact_id [String] either the contact id or contact email
+      # @example Remove contact by ID
+      #   Resend::Contacts.remove(id: "contact_123")
       #
-      # see also: https://resend.com/docs/api-reference/contacts/delete-contact
-      def remove(audience_id, contact_id)
-        path = "audiences/#{audience_id}/contacts/#{contact_id}"
+      # @example Remove contact scoped to an audience
+      #   Resend::Contacts.remove(id: "contact_123", audience_id: "aud_456")
+      #
+      # https://resend.com/docs/api-reference/contacts/delete-contact
+      def remove(params = {})
+        raise ArgumentError, "Missing `id` or `email` field" if params[:id].nil? && params[:email].nil?
+
+        audience_id = params[:audience_id]
+        contact_id = params[:id] || params[:email]
+        path = if audience_id
+                 "audiences/#{audience_id}/contacts/#{contact_id}"
+               else
+                 "contacts/#{contact_id}"
+               end
         Resend::Request.new(path, {}, "delete").perform
       end
 
@@ -51,10 +105,18 @@ module Resend
       # @param params [Hash] the contact params
       # https://resend.com/docs/api-reference/contacts/update-contact
       def update(params)
-        raise ArgumentError, "id or email is required" if params[:id].nil? && params[:email].nil?
+        raise ArgumentError, "Missing `id` or `email` field" if params[:id].nil? && params[:email].nil?
 
-        path = "audiences/#{params[:audience_id]}/contacts/#{params[:id] || params[:email]}"
-        Resend::Request.new(path, params, "patch").perform
+        contact_id = params[:id] || params[:email]
+        if params[:audience_id]
+          path = "audiences/#{params[:audience_id]}/contacts/#{contact_id}"
+          # Audience-scoped contacts don't support properties
+          payload = params.reject { |key, _| key == :properties }
+        else
+          path = "contacts/#{contact_id}"
+          payload = params
+        end
+        Resend::Request.new(path, payload, "patch").perform
       end
     end
   end

data/lib/resend/emails/attachments.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Resend
+  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
+        #   Resend::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}"
+          Resend::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
+        #   Resend::Emails::Attachments.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+        #   )
+        #
+        # @example List with custom limit
+        #   Resend::Emails::Attachments.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+        #     limit: 50
+        #   )
+        #
+        # @example List with pagination
+        #   Resend::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 = Resend::PaginationHelper.build_paginated_path(base_path, pagination_params)
+          Resend::Request.new(path, {}, "get").perform
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Resend
+  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
+          #   Resend::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}"
+            Resend::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
+          #   Resend::Emails::Receiving::Attachments.list(
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+          #   )
+          #
+          # @example List with custom limit
+          #   Resend::Emails::Receiving::Attachments.list(
+          #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+          #     limit: 50
+          #   )
+          #
+          # @example List with pagination
+          #   Resend::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 = Resend::PaginationHelper.build_paginated_path(base_path, pagination_params)
+            Resend::Request.new(path, {}, "get").perform
+          end
+        end
+      end
+    end
+  end
+end

data/lib/resend/emails/receiving.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Resend
+  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
+        #   Resend::Emails::Receiving.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+        def get(email_id = "")
+          path = "emails/receiving/#{email_id}"
+          Resend::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
+        #   Resend::Emails::Receiving.list
+        #
+        # @example List with custom limit
+        #   Resend::Emails::Receiving.list(limit: 50)
+        #
+        # @example List with pagination
+        #   Resend::Emails::Receiving.list(limit: 20, after: "email_id_123")
+        def list(params = {})
+          path = Resend::PaginationHelper.build_paginated_path("emails/receiving", params)
+          Resend::Request.new(path, {}, "get").perform
+        end
+      end
+    end
+  end
+end

data/lib/resend/emails.rb

@@ -51,12 +51,5 @@ module Resend
         Resend::Request.new(path, query_params, "get").perform
       end
     end
-
-    # This method is kept here for backwards compatibility
-    # Use Resend::Emails.send instead.
-    def send_email(params)
-      warn "[DEPRECATION] `send_email` is deprecated.  Please use `Resend::Emails.send` instead."
-      Resend::Emails.send(params)
-    end
   end
 end

data/lib/resend/mailer.rb

@@ -14,7 +14,7 @@ module Resend
       cc bcc
       from reply-to to subject mime-version
       html text
-      content-type tags scheduled_at
+      content-type content-transfer-encoding tags scheduled_at
       headers options
     ].freeze
 

data/lib/resend/request.rb

@@ -34,13 +34,16 @@ module Resend
       resp = HTTParty.send(@verb.to_sym, "#{BASE_URL}#{@path}", options)
 
       check_json!(resp)
-      process_response(resp)
+      data = process_response(resp)
+      headers = extract_headers(resp)
+
+      Resend::Response.new(data, headers)
     end
 
-    def handle_error!(resp)
-      code = resp[:statusCode]
-      body = resp[:message]
-      headers = resp.respond_to?(:headers) ? resp.headers : (resp[:headers] || {})
+    def handle_error!(data, resp = nil)
+      code = data[:statusCode]
+      body = data[:message]
+      headers = resp.respond_to?(:headers) ? resp.headers : (data[:headers] || {})
 
       # get error from the known list of errors
       error_class = Resend::Error::ERRORS[code] || Resend::Error
@@ -66,20 +69,23 @@ module Resend
     end
 
     def process_response(resp)
-      resp.transform_keys!(&:to_sym) unless resp.body.empty?
-      handle_error!(resp) if error_response?(resp)
-      resp
+      # Extract the parsed data from HTTParty response or use the hash directly (for tests/mocks)
+      data = resp.respond_to?(:parsed_response) ? resp.parsed_response : resp
+      data ||= {}
+      data.transform_keys!(&:to_sym) unless resp.body.empty?
+      handle_error!(data, resp) if error_response?(data)
+      data
     end
 
     def error_response?(resp)
-      resp[:statusCode] && (resp[:statusCode] != 200 && resp[:statusCode] != 201)
+      resp[:statusCode] && resp[:statusCode] != 200 && resp[:statusCode] != 201
     end
 
     def set_idempotency_key
       # Only set idempotency key if the verb is POST for now.
       #
       # Does not set it if the idempotency_key is nil or empty
-      if @verb.downcase == "post" && (!@options[:idempotency_key].nil? && !@options[:idempotency_key].empty?)
+      if @verb.downcase == "post" && !@options[:idempotency_key].nil? && !@options[:idempotency_key].empty?
         @headers["Idempotency-Key"] = @options[:idempotency_key]
       end
     end
@@ -101,5 +107,12 @@ module Resend
     rescue JSON::ParserError, TypeError
       raise Resend::Error::InternalServerError.new("Resend API returned an unexpected response", nil)
     end
+
+    # Extract and normalize headers from the HTTParty response
+    def extract_headers(resp)
+      return {} unless resp.respond_to?(:headers)
+
+      resp.headers.to_h.transform_keys { |k| k.to_s.downcase }
+    end
   end
 end

data/lib/resend/response.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Resend
+  # Response wrapper that maintains backwards compatibility while exposing headers
+  #
+  # This class wraps API responses and behaves like a Hash for backwards compatibility,
+  # while also providing access to response headers via the #headers method.
+  #
+  # @example Backwards compatible hash access
+  #   response = Resend::Emails.send(params)
+  #   response[:id]  # => "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
+  #
+  # @example Accessing response headers
+  #   response = Resend::Emails.send(params)
+  #   response.headers  # => {"content-type" => "application/json", ...}
+  #   response.headers['x-ratelimit-remaining']  # => "50"
+  class Response
+    include Enumerable
+
+    # @param data [Hash] The response data
+    # @param headers [Hash, HTTParty::Response] The response headers
+    def initialize(data, headers)
+      @data = data.is_a?(Hash) ? data : {}
+      @headers = normalize_headers(headers)
+    end
+
+    # Access response headers
+    # @return [Hash] Response headers as a hash with lowercase string keys
+    attr_reader :headers
+
+    # Hash-like access via []
+    # @param key [Symbol, String] The key to access
+    # @return [Object] The value at the key
+    def [](key)
+      @data[key]
+    end
+
+    # Hash-like assignment via []=
+    # @param key [Symbol, String] The key to set
+    # @param value [Object] The value to set
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    # Dig into nested hash structure
+    # @param keys [Array<Symbol, String>] Keys to dig through
+    # @return [Object] The value at the nested key path
+    def dig(*keys)
+      @data.dig(*keys)
+    end
+
+    # Convert to plain hash
+    # @return [Hash] The underlying data hash
+    def to_h
+      @data
+    end
+
+    alias to_hash to_h
+
+    # Get all keys from the data
+    # @return [Array] Array of keys
+    def keys
+      @data.keys
+    end
+
+    # Get all values from the data
+    # @return [Array] Array of values
+    def values
+      @data.values
+    end
+
+    # Check if key exists
+    # @param key [Symbol, String] The key to check
+    # @return [Boolean] True if key exists
+    def key?(key)
+      @data.key?(key)
+    end
+
+    alias has_key? key?
+
+    # Enable enumeration over the data
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Transform keys in the underlying data
+    # @return [Resend::Response] Self for chaining
+    def transform_keys!(&block)
+      @data.transform_keys!(&block)
+      self
+    end
+
+    # Check if response is empty
+    # @return [Boolean] True if data is empty
+    def empty?
+      @data.empty?
+    end
+
+    # Respond to hash-like methods
+    def respond_to_missing?(method_name, include_private = false)
+      @data.respond_to?(method_name) || super
+    end
+
+    # Delegate unknown methods to the underlying data hash
+    def method_missing(method_name, *args, &block)
+      if @data.respond_to?(method_name)
+        result = @data.send(method_name, *args, &block)
+        # If the method returns the hash itself, return self to maintain wrapper
+        result.equal?(@data) ? self : result
+      else
+        super
+      end
+    end
+
+    # String representation for debugging
+    # @return [String] String representation of the response
+    def inspect
+      "#<Resend::Response data=#{@data.inspect} headers=#{@headers.keys.inspect}>"
+    end
+
+    private
+
+    # Normalize headers to a simple hash with lowercase string keys
+    # @param headers [Hash, HTTParty::Response, nil] The headers to normalize
+    # @return [Hash] Normalized headers hash
+    def normalize_headers(headers)
+      return {} if headers.nil?
+
+      # Handle HTTParty::Response object
+      headers = headers.headers if headers.respond_to?(:headers)
+
+      # Convert to hash and normalize keys to lowercase strings
+      case headers
+      when Hash
+        headers.to_h.transform_keys { |k| k.to_s.downcase }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/resend/segments.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Resend
+  # Segments api wrapper
+  module Segments
+    class << self
+      # https://resend.com/docs/api-reference/segments/create-segment
+      def create(params)
+        path = "segments"
+        Resend::Request.new(path, params, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/segments/get-segment
+      def get(segment_id = "")
+        path = "segments/#{segment_id}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/segments/list-segments
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("segments", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/segments/delete-segment
+      def remove(segment_id = "")
+        path = "segments/#{segment_id}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+    end
+  end
+end

data/lib/resend/templates.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Resend
+  # Templates api wrapper
+  module Templates
+    class << self
+      # https://resend.com/docs/api-reference/templates/create-template
+      def create(params = {})
+        path = "templates"
+        Resend::Request.new(path, params, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/get-template
+      def get(template_id = "")
+        path = "templates/#{template_id}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/update-template
+      def update(template_id, params = {})
+        path = "templates/#{template_id}"
+        Resend::Request.new(path, params, "patch").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/publish-template
+      def publish(template_id = "")
+        path = "templates/#{template_id}/publish"
+        Resend::Request.new(path, {}, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/duplicate-template
+      def duplicate(template_id = "")
+        path = "templates/#{template_id}/duplicate"
+        Resend::Request.new(path, {}, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/list-templates
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("templates", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/templates/delete-template
+      def remove(template_id = "")
+        path = "templates/#{template_id}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+    end
+  end
+end

data/lib/resend/topics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Resend
+  # Topics api wrapper
+  module Topics
+    class << self
+      # https://resend.com/docs/api-reference/topics/create-topic
+      def create(params = {})
+        path = "topics"
+        Resend::Request.new(path, params, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/topics/get-topic
+      def get(topic_id = "")
+        path = "topics/#{topic_id}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/topics/update-topic
+      def update(params = {})
+        path = "topics/#{params[:topic_id]}"
+        Resend::Request.new(path, params, "patch").perform
+      end
+
+      # https://resend.com/docs/api-reference/topics/list-topics
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("topics", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/topics/delete-topic
+      def remove(topic_id = "")
+        path = "topics/#{topic_id}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+    end
+  end
+end

data/lib/resend/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Resend
-  VERSION = "0.27.0"
+  VERSION = "1.0.1"
 end

data/lib/resend.rb

@@ -8,18 +8,27 @@ require "httparty"
 require "json"
 require "cgi"
 require "resend/errors"
+require "resend/response"
 require "resend/client"
 require "resend/request"
 require "resend/pagination_helper"
 
 # API Operations
-require "resend/audiences"
+require "resend/segments"
 require "resend/api_keys"
 require "resend/broadcasts"
 require "resend/batch"
 require "resend/contacts"
+require "resend/contacts/segments"
+require "resend/contacts/topics"
+require "resend/contact_properties"
 require "resend/domains"
 require "resend/emails"
+require "resend/templates"
+require "resend/emails/receiving"
+require "resend/emails/attachments"
+require "resend/emails/receiving/attachments"
+require "resend/topics"
 require "resend/webhooks"
 
 # Rails
@@ -36,4 +45,7 @@ module Resend
     end
     alias config configure
   end
+
+  # @deprecated Use Segments instead
+  Audiences = Segments
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: resend
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Derich Pacheco
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -38,34 +38,44 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
+description: 
 email: carlosderich@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - lib/resend.rb
 - lib/resend/api_keys.rb
-- lib/resend/audiences.rb
 - lib/resend/batch.rb
 - lib/resend/broadcasts.rb
 - lib/resend/client.rb
+- lib/resend/contact_properties.rb
 - lib/resend/contacts.rb
+- lib/resend/contacts/segments.rb
+- lib/resend/contacts/topics.rb
 - lib/resend/domains.rb
 - lib/resend/emails.rb
+- lib/resend/emails/attachments.rb
+- lib/resend/emails/receiving.rb
+- lib/resend/emails/receiving/attachments.rb
 - lib/resend/errors.rb
 - lib/resend/mailer.rb
 - lib/resend/pagination_helper.rb
 - lib/resend/railtie.rb
 - lib/resend/request.rb
+- lib/resend/response.rb
+- lib/resend/segments.rb
+- lib/resend/templates.rb
+- lib/resend/topics.rb
 - lib/resend/version.rb
 - lib/resend/webhooks.rb
 homepage: https://github.com/resend/resend-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -80,8 +90,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: The Ruby and Rails SDK for resend.com
 test_files: []

data/lib/resend/audiences.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Resend
-  # Audiences api wrapper
-  module Audiences
-    class << self
-      # https://resend.com/docs/api-reference/audiences/create-audience
-      def create(params)
-        path = "audiences"
-        Resend::Request.new(path, params, "post").perform
-      end
-
-      # https://resend.com/docs/api-reference/audiences/get-audience
-      def get(audience_id = "")
-        path = "audiences/#{audience_id}"
-        Resend::Request.new(path, {}, "get").perform
-      end
-
-      # https://resend.com/docs/api-reference/audiences/list-audiences
-      def list(params = {})
-        path = Resend::PaginationHelper.build_paginated_path("audiences", params)
-        Resend::Request.new(path, {}, "get").perform
-      end
-
-      # https://resend.com/docs/api-reference/audiences/delete-audience
-      def remove(audience_id = "")
-        path = "audiences/#{audience_id}"
-        Resend::Request.new(path, {}, "delete").perform
-      end
-    end
-  end
-end