feat: Inbound API (#134)

Co-authored-by: Lucas da Costa <[email protected]>

Author: drish

examples/receiving_emails.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../lib/resend"
+
+raise if ENV["RESEND_API_KEY"].nil?
+
+Resend.api_key = ENV["RESEND_API_KEY"]
+
+puts "=== Listing Received Emails ==="
+
+puts "\nListing all received emails:"
+emails = Resend::Emails::Receiving.list
+
+puts "Total emails in response: #{emails[:data].length}"
+puts "Has more: #{emails[:has_more]}"
+
+emails[:data].each do |e|
+  puts "  - #{e["id"]}: #{e["subject"]} from #{e["from"]}"
+  puts "    Created: #{e["created_at"]}"
+  if e["attachments"] && !e["attachments"].empty?
+    puts "    Attachments: #{e["attachments"].length}"
+  end
+end
+
+puts "\n\nListing with limit of 5:"
+limited_emails = Resend::Emails::Receiving.list(limit: 5)
+
+puts "Retrieved #{limited_emails[:data].length} emails"
+puts "Has more: #{limited_emails[:has_more]}"
+
+# Example of pagination (if you have more emails)
+if limited_emails[:has_more] && limited_emails[:data].last
+  last_id = limited_emails[:data].last["id"]
+  puts "\n\nGetting next page after ID: #{last_id}"
+  next_page = Resend::Emails::Receiving.list(limit: 5, after: last_id)
+  puts "Next page has #{next_page[:data].length} emails"
+end
+
+puts "\n\n=== Retrieving Single Received Email ==="
+
+# Use the first email from the list, or specify a known ID
+if emails[:data] && emails[:data].first
+  email_id = emails[:data].first["id"]
+else
+  # Replace with an actual received email ID from your account
+  email_id = "006e2796-ff6a-4436-91ad-0429e600bf8a"
+end
+
+email = Resend::Emails::Receiving.get(email_id)
+
+puts "\nEmail Details:"
+puts "  ID: #{email[:id]}"
+puts "  From: #{email[:from]}"
+puts "  To: #{email[:to].join(', ')}"
+puts "  Subject: #{email[:subject]}"
+puts "  Created At: #{email[:created_at]}"
+puts "  Message ID: #{email[:message_id]}"
+
+if email[:cc] && !email[:cc].empty?
+  puts "  CC: #{email[:cc].join(', ')}"
+end
+
+if email[:bcc] && !email[:bcc].empty?
+  puts "  BCC: #{email[:bcc].join(', ')}"
+end
+
+if email[:attachments] && !email[:attachments].empty?
+  puts "\n  Attachments:"
+  email[:attachments].each do |attachment|
+    puts "    - #{attachment["filename"]} (#{attachment["content_type"]})"
+    puts "      ID: #{attachment["id"]}"
+    puts "      Size: #{attachment["size"]} bytes" if attachment["size"]
+    puts "      Content ID: #{attachment["content_id"]}" if attachment["content_id"]
+  end
+
+  puts "\n  Listing all attachments for email: #{email[:id]}"
+  attachments_list = Resend::Attachments::Receiving.list(
+    email_id: email[:id]
+  )
+
+  puts "    Total attachments: #{attachments_list[:data].length}"
+  puts "    Has more: #{attachments_list[:has_more]}"
+
+  # Retrieve full attachment details for the first attachment
+  if email[:attachments].first
+    first_attachment_id = email[:attachments].first["id"]
+    puts "\n  Retrieving full attachment details for: #{first_attachment_id}"
+
+    attachment_details = Resend::Attachments::Receiving.get(
+      id: first_attachment_id,
+      email_id: email[:id]
+    )
+
+    puts "    Download URL: #{attachment_details[:download_url]}"
+    puts "    Expires At: #{attachment_details[:expires_at]}"
+  end
+end
+
+puts "\n  HTML Content:"
+puts "  #{email[:html][0..100]}..." if email[:html]
+
+puts "\n  Text Content:"
+puts "  #{email[:text]}" if email[:text]

lib/resend.rb

@@ -20,6 +20,8 @@
 require "resend/contacts"
 require "resend/domains"
 require "resend/emails"
+require "resend/emails/receiving"
+require "resend/attachments/receiving"
 require "resend/topics"
 
 # Rails

lib/resend/attachments/receiving.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Resend
+  module Attachments
+    # Module for receiving email attachments API operations
+    module Receiving
+      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::Attachments::Receiving.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::Attachments::Receiving.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
+        #   )
+        #
+        # @example List with custom limit
+        #   Resend::Attachments::Receiving.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+        #     limit: 50
+        #   )
+        #
+        # @example List with pagination
+        #   Resend::Attachments::Receiving.list(
+        #     email_id: "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
+        #     limit: 20,
+        #     after: "attachment_id_123"
+        #   )
+        def list(params = {})
+          email_id = params[:email_id]
+          path = "emails/receiving/#{email_id}/attachments"
+
+          # Build query parameters, filtering out nil values
+          query_params = {}
+          query_params[:limit] = params[:limit] if params[:limit]
+          query_params[:after] = params[:after] if params[:after]
+          query_params[:before] = params[:before] if params[:before]
+
+          Resend::Request.new(path, query_params, "get").perform
+        end
+      end
+    end
+  end
+end

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