resend 0.27.0 → 1.6.0

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/domains/claims.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Resend
+  module Domains
+    # Domain Claims API wrapper
+    module Claims
+      class << self
+        #
+        # Start a claim for a domain that another Resend account has already verified.
+        # The domain is recreated under your account with fresh DKIM keys, so the
+        # previous account's DNS records cannot be reused. Returns a TXT record to add
+        # to your DNS to prove ownership. Uses the same request body as creating a domain.
+        #
+        # @param params [Hash] the parameters
+        # @option params [String] :name the name of the domain you want to claim (required)
+        # @option params [String] :region the region where emails will be sent from.
+        #   Possible values: 'us-east-1' | 'eu-west-1' | 'sa-east-1' | 'ap-northeast-1'
+        # @option params [String] :custom_return_path subdomain for the Return-Path address (default 'send')
+        # @option params [String] :tracking_subdomain the custom subdomain used for click and open tracking links
+        # @option params [Boolean] :click_tracking track clicks within the body of each HTML email
+        # @option params [Boolean] :open_tracking track the open rate of each email
+        #
+        # https://resend.com/docs/api-reference/domains/claim-domain
+        def create(params)
+          path = "domains/claim"
+          Resend::Request.new(path, params, "post").perform
+        end
+
+        #
+        # Retrieve the latest claim for the placeholder domain created by the claim.
+        #
+        # @param domain_id [String] the ID of the placeholder domain created by the claim
+        #
+        # https://resend.com/docs/api-reference/domains/get-domain-claim
+        def get(domain_id = "")
+          path = "domains/#{domain_id}/claim"
+          Resend::Request.new(path, {}, "get").perform
+        end
+
+        #
+        # Trigger asynchronous DNS verification and ownership transfer for a domain claim.
+        # The claim stays 'pending' while verification runs; poll `get` for status. Once
+        # 'completed', the transferred domain has new DKIM records that must be added to
+        # DNS and verified via Resend::Domains.verify.
+        #
+        # @param domain_id [String] the ID of the placeholder domain created by the claim
+        #
+        # https://resend.com/docs/api-reference/domains/verify-domain-claim
+        def verify(domain_id = "")
+          path = "domains/#{domain_id}/claim/verify"
+          Resend::Request.new(path, {}, "post").perform
+        end
+      end
+    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,51 @@
+# 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
+        # @param params [Hash] Optional query parameters
+        # @option params [String] :html_format Format of the HTML content (e.g., "sanitized", "raw")
+        # @return [Hash] The received email object
+        #
+        # @example
+        #   Resend::Emails::Receiving.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+        #
+        # @example With html_format
+        #   Resend::Emails::Receiving.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c", html_format: "sanitized")
+        def get(email_id = "", params = {})
+          path = "emails/receiving/#{email_id}"
+
+          path += "?html_format=#{CGI.escape(params[:html_format].to_s)}" if params[:html_format]
+
+          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/events.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Resend
+  # events api wrapper
+  module Events
+    class << self
+      # https://resend.com/docs/api-reference/events/create-event
+      def create(params = {})
+        Resend::Request.new("events", params, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/events/get-event
+      # identifier can be a UUID or an event name (e.g. "user.signed_up")
+      def get(identifier = "")
+        path = "events/#{CGI.escape(identifier.to_s)}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/events/update-event
+      def update(params = {})
+        identifier = params[:identifier]
+        path = "events/#{CGI.escape(identifier.to_s)}"
+        payload = params.reject { |k, _| k == :identifier }
+        Resend::Request.new(path, payload, "patch").perform
+      end
+
+      # https://resend.com/docs/api-reference/events/delete-event
+      # identifier can be a UUID or an event name (e.g. "user.signed_up")
+      def remove(identifier = "")
+        path = "events/#{CGI.escape(identifier.to_s)}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+
+      # https://resend.com/docs/api-reference/events/send-event
+      def send(params = {})
+        Resend::Request.new("events/send", params, "post").perform
+      end
+
+      # https://resend.com/docs/api-reference/events/list-events
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("events", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+    end
+  end
+end

data/lib/resend/logs.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Resend
+  # logs api wrapper
+  module Logs
+    class << self
+      # https://resend.com/docs/api-reference/logs/retrieve-log
+      def get(log_id = "")
+        path = "logs/#{log_id}"
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/logs/list-logs
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("logs", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+    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/multipart_request.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Resend
+  # Handles multipart/form-data requests (file uploads).
+  # Builds the multipart body directly instead of relying on HTTParty's
+  # duck-typing file detection, which requires a :path method.
+  class MultipartRequest < Request
+    NEWLINE = "\r\n"
+    private_constant :NEWLINE
+
+    private
+
+    def build_request_options
+      boundary = SecureRandom.hex(16)
+      headers = @headers.merge("Content-Type" => "multipart/form-data; boundary=#{boundary}")
+      { headers: headers, body: build_multipart_body(boundary) }
+    end
+
+    def build_multipart_body(boundary)
+      body = "".b
+
+      body << part(boundary, "file", read_file(@body[:file]), filename: "import.csv", content_type: "text/csv")
+      optional_fields.each { |name, value| body << part(boundary, name, value) }
+      body << "--#{boundary}--#{NEWLINE}".b
+
+      body
+    end
+
+    def part(boundary, name, value, filename: nil, content_type: nil)
+      disposition = %(Content-Disposition: form-data; name="#{name}")
+      disposition += %(; filename="#{filename}") if filename
+
+      header = "--#{boundary}#{NEWLINE}#{disposition}#{NEWLINE}"
+      header += "Content-Type: #{content_type}#{NEWLINE}" if content_type
+      header += NEWLINE
+
+      header.b + value.to_s.b + NEWLINE.b
+    end
+
+    def read_file(file_data)
+      if file_data.respond_to?(:read)
+        content = file_data.read
+        file_data.rewind if file_data.respond_to?(:rewind)
+        content.b
+      else
+        file_data.to_s.b
+      end
+    end
+
+    def optional_fields
+      {
+        column_map: @body[:column_map] && serialize_json(@body[:column_map]),
+        on_conflict: @body[:on_conflict],
+        segments: @body[:segments] && serialize_json(@body[:segments]),
+        topics: @body[:topics] && serialize_json(@body[:topics])
+      }.compact
+    end
+
+    def serialize_json(value)
+      return value if value.is_a?(String)
+
+      value.to_json
+    end
+  end
+end

data/lib/resend/oauth_grants.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Resend
+  # oauth grants api wrapper
+  module OAuthGrants
+    class << self
+      # https://resend.com/docs/api-reference/oauth/list-grants
+      def list(params = {})
+        path = Resend::PaginationHelper.build_paginated_path("oauth/grants", params)
+        Resend::Request.new(path, {}, "get").perform
+      end
+
+      # https://resend.com/docs/api-reference/oauth/revoke-grant
+      def revoke(oauth_grant_id = "")
+        path = "oauth/grants/#{oauth_grant_id}"
+        Resend::Request.new(path, {}, "delete").perform
+      end
+    end
+  end
+end

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