mailshake-ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dac51d36d81055f0ee4b47e3e0cbebef824b7b7b88168d2327869d8fa9ec6b8b
-  data.tar.gz: e595b5f7e002badc7ab1f1035fcd95500e27686f074aba1cbbc6a72801cb9bad
+  metadata.gz: 328a77f17bacfe02fc4a7a4a869a1aa78bde71a05096c95057e7a9586c380a75
+  data.tar.gz: 07323100c2bfc0a3743c60204d248860dd04b784c79cdba0e060a168b659e963
 SHA512:
-  metadata.gz: d98021363059d25659da7be92cd6e69fe0219e029b661f709fc8dc0a73a20d0412374c66bfa75b348a07c06070f0acf55d18e8bcbd5a7c5586e33c6b0b39650f
-  data.tar.gz: e2d4bc194b916370ba0c0e059ecd06e74052eb662265e13ed1d8f5bce58862c14d8cbf28c7515fec5f20eb5f7c53075557c6a0d3a4df9bae08317c1693bdc4fb
+  metadata.gz: cb67630c178d246c30d3c10ab59f94b4e19c93a1f9e2423814bf9db3f641f5cc2eed12bdc8822b5c52f4d1e82c7a6b3d23d1de51cad5f6ab5e1c26a3590c0247
+  data.tar.gz: de3dc3ef281a458821178873fc05c6bb1e36d1ea252adaee6991869c8b5b86e8a6f9f5e67785b9ca23fa4cc36f1c06389ce1fa618443da674ebdccfbdfb4bd1f

data/README.md

@@ -32,18 +32,29 @@ end
 
 ## Usage
 
+All API responses return model objects with snake_case accessors and nested model hydration. Hash-style access (`result["key"]`) is still supported for backwards compatibility.
+
 ### Campaigns
 
 ```ruby
 campaigns = Mailshake::Campaigns.new
 
-campaigns.list(search: "onboarding", per_page: 10)
-campaigns.get(campaign_id: 1)
+list = campaigns.list(search: "onboarding", per_page: 10)
+list.each { |c| puts c.title }
+
+campaign = campaigns.get(campaign_id: 1)
+campaign.title                    # => "Q2 Outreach"
+campaign.is_paused                # => false
+campaign.sender.email_address     # => "sales@company.com"
+campaign.messages.first.subject   # => "Hey {{first}}"
+
 campaigns.create(title: "Q2 Outreach", sender_id: 5)
 campaigns.pause(campaign_id: 1)
 campaigns.unpause(campaign_id: 1)
-campaigns.export(campaign_ids: [1, 2], export_type: "csv", timezone: "US/Pacific")
-campaigns.export_status(status_id: 42)
+
+export = campaigns.export(campaign_ids: [1, 2], export_type: "csv", timezone: "US/Pacific")
+status = campaigns.export_status(status_id: export.check_status_id)
+puts status.csv_download_url if status.is_finished
 ```
 
 ### Recipients
@@ -51,10 +62,16 @@ campaigns.export_status(status_id: 42)
 ```ruby
 recipients = Mailshake::Recipients.new
 
-recipients.add(campaign_id: 1, addresses: [{ emailAddress: "john@example.com" }])
-recipients.add_status(status_id: 42)
-recipients.list(campaign_id: 1, filter: "active", per_page: 25)
-recipients.get(recipient_id: 100)
+result = recipients.add(campaign_id: 1, addresses: [{ emailAddress: "john@example.com" }])
+status = recipients.add_status(status_id: result.check_status_id)
+
+list = recipients.list(campaign_id: 1, filter: "active", per_page: 25)
+list.each { |r| puts "#{r.full_name} <#{r.email_address}>" }
+
+recipient = recipients.get(recipient_id: 100)
+recipient.email_address  # => "john@example.com"
+recipient.is_paused      # => false
+
 recipients.pause(campaign_id: 1, email_address: "john@example.com")
 recipients.unpause(campaign_id: 1, email_address: "john@example.com")
 recipients.unsubscribe(email_addresses: ["john@example.com"])
@@ -65,10 +82,18 @@ recipients.unsubscribe(email_addresses: ["john@example.com"])
 ```ruby
 activity = Mailshake::Activity.new
 
-activity.sent(campaign_id: 1, per_page: 50)
-activity.opens(campaign_id: 1, exclude_duplicates: true)
-activity.clicks(campaign_id: 1, match_url: "https://example.com")
-activity.replies(campaign_id: 1, reply_type: "reply")
+sent = activity.sent(campaign_id: 1, per_page: 50)
+sent.each { |msg| puts "#{msg.subject} -> #{msg.recipient.email_address}" }
+
+opens = activity.opens(campaign_id: 1, exclude_duplicates: true)
+opens.each { |o| puts "#{o.recipient.email_address} opened at #{o.action_date}" }
+
+clicks = activity.clicks(campaign_id: 1, match_url: "https://example.com")
+clicks.each { |c| puts "#{c.recipient.email_address} clicked #{c.link}" }
+
+replies = activity.replies(campaign_id: 1, reply_type: "reply")
+replies.each { |r| puts "#{r.recipient.email_address}: #{r.plain_text_body}" }
+
 activity.created_leads(campaign_id: 1, since: "2026-01-01")
 activity.lead_assignments(campaign_id: 1)
 activity.lead_status_changes(campaign_id: 1)
@@ -79,8 +104,17 @@ activity.lead_status_changes(campaign_id: 1)
 ```ruby
 leads = Mailshake::Leads.new
 
-leads.list(campaign_id: 1, status: "open")
-leads.get(lead_id: 42)
+list = leads.list(campaign_id: 1, status: "open")
+list.each do |lead|
+  puts "#{lead.recipient.email_address} - #{lead.status}"
+  puts "  assigned to: #{lead.assigned_to&.full_name}"
+end
+
+lead = leads.get(lead_id: 42)
+lead.status                   # => "open"
+lead.recipient.email_address  # => "john@example.com"
+lead.campaign.title           # => "Q2 Outreach"
+
 leads.create(campaign_id: 1, email_addresses: ["john@example.com"])
 leads.close(lead_id: 42, status: "won")
 leads.ignore(lead_id: 42)
@@ -92,7 +126,8 @@ leads.reopen(lead_id: 42)
 ```ruby
 team = Mailshake::Team.new
 
-team.list_members(search: "john", per_page: 10)
+members = team.list_members(search: "john", per_page: 10)
+members.each { |u| puts "#{u.full_name} <#{u.email_address}>" }
 ```
 
 ### Senders
@@ -100,7 +135,8 @@ team.list_members(search: "john", per_page: 10)
 ```ruby
 senders = Mailshake::Senders.new
 
-senders.list(search: "sales", per_page: 10)
+list = senders.list(search: "sales", per_page: 10)
+list.each { |s| puts "#{s.from_name} <#{s.email_address}>" }
 ```
 
 ### Push/Webhooks
@@ -116,16 +152,41 @@ push.delete(target_url: "https://example.com/webhook")
 
 ```ruby
 client = Mailshake.client
-client.me
+user = client.me
+user.full_name      # => "Eduardo Souza"
+user.email_address  # => "eduardo@example.com"
+user.is_team_admin  # => true
 ```
 
+## Models
+
+All responses are wrapped in model objects under `Mailshake::Models`. Models provide:
+
+- **Snake_case accessors** - `campaign.is_paused` instead of `campaign["isPaused"]`
+- **Nested model hydration** - `lead.recipient.email_address` returns a `Recipient` model
+- **Backwards compatibility** - `campaign["title"]` still works
+- **`to_h`** - convert back to the original hash
+
+See the [full model reference](https://github.com/ESouza/mailshake-ruby/wiki/Models) in the wiki.
+
 ## Pagination
 
-Endpoints that return lists support pagination via `next_token` and `per_page`:
+List endpoints return a `Models::List` object with `Enumerable` support:
 
 ```ruby
 result = campaigns.list(per_page: 10)
-next_page = campaigns.list(per_page: 10, next_token: result["nextToken"])
+result.each { |c| puts c.title }
+result.map(&:title)
+
+# Paginate through all results
+all = []
+result = campaigns.list(per_page: 25)
+all.concat(result.results)
+
+while result.next_token
+  result = campaigns.list(per_page: 25, next_token: result.next_token)
+  all.concat(result.results)
+end
 ```
 
 ## Error Handling

data/lib/mailshake/activity.rb

@@ -3,7 +3,7 @@
 module Mailshake
   class Activity < Base
     def sent(message_type: nil, campaign_message_type: nil, campaign_id: nil, recipient_email_address: nil, exclude_body: nil, next_token: nil, per_page: nil)
-      client.get("/activity/sent", camelize_params(
+      response = client.get("/activity/sent", camelize_params(
         message_type: message_type,
         campaign_message_type: campaign_message_type,
         campaign_id: campaign_id,
@@ -12,10 +12,11 @@ module Mailshake
         next_token: next_token,
         per_page: per_page
       ))
+      Models::List.new(response, Models::SentMessage)
     end
 
     def opens(campaign_id: nil, exclude_duplicates: nil, recipient_email_address: nil, next_token: nil, per_page: nil, since: nil)
-      client.get("/activity/opens", camelize_params(
+      response = client.get("/activity/opens", camelize_params(
         campaign_id: campaign_id,
         exclude_duplicates: exclude_duplicates,
         recipient_email_address: recipient_email_address,
@@ -23,10 +24,11 @@ module Mailshake
         per_page: per_page,
         since: since
       ))
+      Models::List.new(response, Models::Open)
     end
 
     def clicks(campaign_id: nil, exclude_duplicates: nil, match_url: nil, recipient_email_address: nil, next_token: nil, per_page: nil, since: nil)
-      client.get("/activity/clicks", camelize_params(
+      response = client.get("/activity/clicks", camelize_params(
         campaign_id: campaign_id,
         exclude_duplicates: exclude_duplicates,
         match_url: match_url,
@@ -35,20 +37,22 @@ module Mailshake
         per_page: per_page,
         since: since
       ))
+      Models::List.new(response, Models::Click)
     end
 
     def replies(reply_type: nil, campaign_id: nil, recipient_email_address: nil, next_token: nil, per_page: nil)
-      client.get("/activity/replies", camelize_params(
+      response = client.get("/activity/replies", camelize_params(
         reply_type: reply_type,
         campaign_id: campaign_id,
         recipient_email_address: recipient_email_address,
         next_token: next_token,
         per_page: per_page
       ))
+      Models::List.new(response, Models::Reply)
     end
 
     def created_leads(campaign_id: nil, recipient_email_address: nil, assigned_to_email_address: nil, next_token: nil, per_page: nil, since: nil)
-      client.get("/activity/created-leads", camelize_params(
+      response = client.get("/activity/created-leads", camelize_params(
         campaign_id: campaign_id,
         recipient_email_address: recipient_email_address,
         assigned_to_email_address: assigned_to_email_address,
@@ -56,19 +60,21 @@ module Mailshake
         per_page: per_page,
         since: since
       ))
+      Models::List.new(response, Models::Lead)
     end
 
     def lead_assignments(campaign_id: nil, next_token: nil, per_page: nil, since: nil)
-      client.get("/activity/lead-assignments", camelize_params(
+      response = client.get("/activity/lead-assignments", camelize_params(
         campaign_id: campaign_id,
         next_token: next_token,
         per_page: per_page,
         since: since
       ))
+      Models::List.new(response, Models::Lead)
     end
 
     def lead_status_changes(campaign_id: nil, recipient_email_address: nil, assigned_to_email_address: nil, next_token: nil, per_page: nil, since: nil)
-      client.get("/activity/lead-status-changes", camelize_params(
+      response = client.get("/activity/lead-status-changes", camelize_params(
         campaign_id: campaign_id,
         recipient_email_address: recipient_email_address,
         assigned_to_email_address: assigned_to_email_address,
@@ -76,6 +82,7 @@ module Mailshake
         per_page: per_page,
         since: since
       ))
+      Models::List.new(response, Models::LeadStatus)
     end
   end
 end

data/lib/mailshake/campaigns.rb

@@ -3,15 +3,18 @@
 module Mailshake
   class Campaigns < Base
     def list(search: nil, next_token: nil, per_page: nil)
-      client.get("/campaigns/list", camelize_params(search: search, next_token: next_token, per_page: per_page))
+      response = client.get("/campaigns/list", camelize_params(search: search, next_token: next_token, per_page: per_page))
+      Models::List.new(response, Models::Campaign)
     end
 
     def get(campaign_id:)
-      client.get("/campaigns/get", camelize_params(campaign_id: campaign_id))
+      response = client.get("/campaigns/get", camelize_params(campaign_id: campaign_id))
+      Models::Campaign.new(response)
     end
 
     def create(title:, sender_id: nil)
-      client.post("/campaigns/create", camelize_params(title: title, sender_id: sender_id))
+      response = client.post("/campaigns/create", camelize_params(title: title, sender_id: sender_id))
+      Models::Campaign.new(response)
     end
 
     def pause(campaign_id:)
@@ -23,11 +26,13 @@ module Mailshake
     end
 
     def export(campaign_ids: nil, export_type: nil, timezone: nil)
-      client.post("/campaigns/export", camelize_params(campaign_ids: campaign_ids, export_type: export_type, timezone: timezone))
+      response = client.post("/campaigns/export", camelize_params(campaign_ids: campaign_ids, export_type: export_type, timezone: timezone))
+      Models::CampaignExportRequest.new(response)
     end
 
     def export_status(status_id:)
-      client.get("/campaigns/export-status", camelize_params(status_id: status_id))
+      response = client.get("/campaigns/export-status", camelize_params(status_id: status_id))
+      Models::CampaignExport.new(response)
     end
   end
 end

data/lib/mailshake/client.rb

@@ -22,7 +22,8 @@ module Mailshake
     end
 
     def me
-      get("/me")
+      response = get("/me")
+      Models::User.new(response)
     end
 
     private
@@ -63,7 +64,9 @@ module Mailshake
     def handle_response(response)
       case response.code
       when 200, 201, 202, 204
-        response.parsed_response
+        parsed = response.parsed_response
+        check_for_limit_errors(parsed, response)
+        parsed
       when 401
         raise AuthenticationError, "Authentication failed: #{response.body}"
       when 404
@@ -73,6 +76,7 @@ module Mailshake
         raise RateLimitError.new("Rate limit exceeded", response.code, response.body, retry_after)
       when 400, 422
         parsed = response.parsed_response || {}
+        check_for_limit_errors(parsed, response)
         errors = parsed['errors'] || {}
         raise ValidationError.new(
           parsed['message'] || 'Validation failed',
@@ -86,5 +90,22 @@ module Mailshake
         raise APIError.new("Unexpected response", response.code, response.body)
       end
     end
+
+    def check_for_limit_errors(parsed, response)
+      return unless parsed.is_a?(Hash)
+
+      error_code = parsed['error'] || parsed['errorCode']
+      return unless error_code
+
+      case error_code
+      when 'limit_reached'
+        retry_after = parsed['retryAfter']
+        message = parsed['message'] || "Quota limit reached"
+        raise LimitReachedError.new(message, response.code, response.body, retry_after)
+      when 'exceeds_monthly_recipients'
+        message = parsed['message'] || "Monthly recipient limit exceeded"
+        raise MonthlyRecipientLimitError.new(message, response.code, response.body)
+      end
+    end
   end
 end

data/lib/mailshake/errors.rb

@@ -48,4 +48,19 @@ module Mailshake
       @retry_after = retry_after
     end
   end
+
+  class LimitReachedError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "Quota limit reached", status_code = nil, response_body = nil, retry_after = nil)
+      super(message, status_code, response_body)
+      @retry_after = retry_after
+    end
+  end
+
+  class MonthlyRecipientLimitError < APIError
+    def initialize(message = "Monthly recipient limit exceeded", status_code = nil, response_body = nil)
+      super(message, status_code, response_body)
+    end
+  end
 end

data/lib/mailshake/leads.rb

@@ -3,7 +3,7 @@
 module Mailshake
   class Leads < Base
     def list(campaign_id: nil, status: nil, assigned_to_email_address: nil, search: nil, next_token: nil, per_page: nil)
-      client.get("/leads/list", camelize_params(
+      response = client.get("/leads/list", camelize_params(
         campaign_id: campaign_id,
         status: status,
         assigned_to_email_address: assigned_to_email_address,
@@ -11,23 +11,26 @@ module Mailshake
         next_token: next_token,
         per_page: per_page
       ))
+      Models::List.new(response, Models::Lead)
     end
 
     def get(lead_id: nil, recipient_id: nil, campaign_id: nil, email_address: nil)
-      client.get("/leads/get", camelize_params(
+      response = client.get("/leads/get", camelize_params(
         lead_id: lead_id,
         recipient_id: recipient_id,
         campaign_id: campaign_id,
         email_address: email_address
       ))
+      Models::Lead.new(response)
     end
 
     def create(campaign_id:, email_addresses: nil, recipient_ids: nil)
-      client.post("/leads/create", camelize_params(
+      response = client.post("/leads/create", camelize_params(
         campaign_id: campaign_id,
         email_addresses: email_addresses,
         recipient_ids: recipient_ids
       ))
+      Models::CreatedLeads.new(response)
     end
 
     def close(lead_id: nil, campaign_id: nil, email_address: nil, recipient_id: nil, status: nil)

data/lib/mailshake/models/add_recipients_request.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class AddRecipientsRequest < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/added_recipients.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class AddedRecipients < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/base_model.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class BaseModel
+      class << self
+        def has_one(field, klass)
+          nested_one[field.to_s] = klass
+        end
+
+        def has_many(field, klass)
+          nested_many[field.to_s] = klass
+        end
+
+        def nested_one
+          @nested_one ||= {}
+        end
+
+        def nested_many
+          @nested_many ||= {}
+        end
+      end
+
+      attr_reader :data
+
+      def initialize(data = {})
+        @data = data || {}
+        define_accessors
+      end
+
+      def [](key)
+        @data[key]
+      end
+
+      def to_h
+        @data
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @accessors&.key?(method_name.to_s) || super
+      end
+
+      private
+
+      def define_accessors
+        @accessors = {}
+        @data.each do |key, value|
+          snake_key = underscore(key.to_s)
+          hydrated = hydrate(snake_key, value)
+          @accessors[snake_key] = hydrated
+
+          define_singleton_method(snake_key) { @accessors[snake_key] }
+        end
+      end
+
+      def hydrate(snake_key, value)
+        one_klass = self.class.nested_one[snake_key]
+        many_klass = self.class.nested_many[snake_key]
+
+        if one_klass && value.is_a?(Hash)
+          one_klass.new(value)
+        elsif many_klass && value.is_a?(Array)
+          value.map { |item| item.is_a?(Hash) ? many_klass.new(item) : item }
+        else
+          value
+        end
+      end
+
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.dup
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+    end
+  end
+end

data/lib/mailshake/models/campaign.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Campaign < BaseModel
+      has_one :sender, Sender
+      has_many :messages, Message
+    end
+  end
+end

data/lib/mailshake/models/campaign_export.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class CampaignExport < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/campaign_export_request.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class CampaignExportRequest < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/click.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Click < BaseModel
+      has_one :recipient, Recipient
+      has_one :campaign, Campaign
+      has_one :parent, SentMessage
+    end
+  end
+end

data/lib/mailshake/models/created_leads.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class CreatedLeads < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/lead.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Lead < BaseModel
+      has_one :recipient, Recipient
+      has_one :campaign, Campaign
+      has_one :assigned_to, User
+    end
+  end
+end

data/lib/mailshake/models/lead_status.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class LeadStatus < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/list.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class List
+      include Enumerable
+
+      attr_reader :results, :next_token, :data
+
+      def initialize(data, model_class)
+        @data = data || {}
+        raw_results = @data["results"] || []
+        @results = raw_results.map { |item| item.is_a?(Hash) ? model_class.new(item) : item }
+        @next_token = @data["nextToken"]
+      end
+
+      def each(&block)
+        @results.each(&block)
+      end
+
+      def [](key)
+        @data[key]
+      end
+
+      def to_h
+        @data
+      end
+    end
+  end
+end

data/lib/mailshake/models/message.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Message < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/open.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Open < BaseModel
+      has_one :recipient, Recipient
+      has_one :campaign, Campaign
+      has_one :parent, SentMessage
+    end
+  end
+end

data/lib/mailshake/models/recipient.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Recipient < BaseModel
+    end
+  end
+end

data/lib/mailshake/models/reply.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Reply < BaseModel
+      has_one :recipient, Recipient
+      has_one :campaign, Campaign
+      has_one :parent, SentMessage
+    end
+  end
+end

data/lib/mailshake/models/sender.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mailshake
+  module Models
+    class Sender < BaseModel
+    end
+  end
+end