mailshake-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dac51d36d81055f0ee4b47e3e0cbebef824b7b7b88168d2327869d8fa9ec6b8b
+  data.tar.gz: e595b5f7e002badc7ab1f1035fcd95500e27686f074aba1cbbc6a72801cb9bad
+SHA512:
+  metadata.gz: d98021363059d25659da7be92cd6e69fe0219e029b661f709fc8dc0a73a20d0412374c66bfa75b348a07c06070f0acf55d18e8bcbd5a7c5586e33c6b0b39650f
+  data.tar.gz: e2d4bc194b916370ba0c0e059ecd06e74052eb662265e13ed1d8f5bce58862c14d8cbf28c7515fec5f20eb5f7c53075557c6a0d3a4df9bae08317c1693bdc4fb

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0] - 2026-04-02
+
+### Added
+- Initial release
+- Campaigns API (list, get, create, pause, unpause, export, export_status)
+- Recipients API (add, add_status, list, get, pause, unpause, unsubscribe)
+- Activity API (sent, opens, clicks, replies, created_leads, lead_assignments, lead_status_changes)
+- Leads API (list, get, create, close, ignore, reopen)
+- Team API (list_members)
+- Senders API (list)
+- Push/Webhooks API (create, delete)
+- Me endpoint
+- API key authentication via Basic Auth
+- Automatic snake_case to camelCase parameter conversion
+- Comprehensive RSpec test suite

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Eduardo Souza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# Mailshake Ruby
+
+Ruby gem for the [Mailshake](https://mailshake.com) email outreach API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mailshake-ruby'
+```
+
+Then run:
+
+```
+bundle install
+```
+
+Or install directly:
+
+```
+gem install mailshake-ruby
+```
+
+## Configuration
+
+```ruby
+Mailshake.configure do |config|
+  config.api_key = ENV['MAILSHAKE_API_KEY']
+end
+```
+
+## Usage
+
+### Campaigns
+
+```ruby
+campaigns = Mailshake::Campaigns.new
+
+campaigns.list(search: "onboarding", per_page: 10)
+campaigns.get(campaign_id: 1)
+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)
+```
+
+### Recipients
+
+```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)
+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"])
+```
+
+### Activity
+
+```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")
+activity.created_leads(campaign_id: 1, since: "2026-01-01")
+activity.lead_assignments(campaign_id: 1)
+activity.lead_status_changes(campaign_id: 1)
+```
+
+### Leads
+
+```ruby
+leads = Mailshake::Leads.new
+
+leads.list(campaign_id: 1, status: "open")
+leads.get(lead_id: 42)
+leads.create(campaign_id: 1, email_addresses: ["john@example.com"])
+leads.close(lead_id: 42, status: "won")
+leads.ignore(lead_id: 42)
+leads.reopen(lead_id: 42)
+```
+
+### Team
+
+```ruby
+team = Mailshake::Team.new
+
+team.list_members(search: "john", per_page: 10)
+```
+
+### Senders
+
+```ruby
+senders = Mailshake::Senders.new
+
+senders.list(search: "sales", per_page: 10)
+```
+
+### Push/Webhooks
+
+```ruby
+push = Mailshake::Push.new
+
+push.create(target_url: "https://example.com/webhook", event: "reply")
+push.delete(target_url: "https://example.com/webhook")
+```
+
+### Me
+
+```ruby
+client = Mailshake.client
+client.me
+```
+
+## Pagination
+
+Endpoints that return lists support pagination via `next_token` and `per_page`:
+
+```ruby
+result = campaigns.list(per_page: 10)
+next_page = campaigns.list(per_page: 10, next_token: result["nextToken"])
+```
+
+## Error Handling
+
+```ruby
+begin
+  campaigns.get(campaign_id: 999)
+rescue Mailshake::AuthenticationError => e
+  puts "Bad API key"
+rescue Mailshake::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Mailshake::RateLimitError => e
+  puts "Rate limited, retry after: #{e.retry_after}"
+rescue Mailshake::ValidationError => e
+  puts "Validation errors: #{e.errors}"
+rescue Mailshake::APIError => e
+  puts "API error #{e.status_code}: #{e.message}"
+end
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/mailshake/activity.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+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(
+        message_type: message_type,
+        campaign_message_type: campaign_message_type,
+        campaign_id: campaign_id,
+        recipient_email_address: recipient_email_address,
+        exclude_body: exclude_body,
+        next_token: next_token,
+        per_page: per_page
+      ))
+    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(
+        campaign_id: campaign_id,
+        exclude_duplicates: exclude_duplicates,
+        recipient_email_address: recipient_email_address,
+        next_token: next_token,
+        per_page: per_page,
+        since: since
+      ))
+    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(
+        campaign_id: campaign_id,
+        exclude_duplicates: exclude_duplicates,
+        match_url: match_url,
+        recipient_email_address: recipient_email_address,
+        next_token: next_token,
+        per_page: per_page,
+        since: since
+      ))
+    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(
+        reply_type: reply_type,
+        campaign_id: campaign_id,
+        recipient_email_address: recipient_email_address,
+        next_token: next_token,
+        per_page: per_page
+      ))
+    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(
+        campaign_id: campaign_id,
+        recipient_email_address: recipient_email_address,
+        assigned_to_email_address: assigned_to_email_address,
+        next_token: next_token,
+        per_page: per_page,
+        since: since
+      ))
+    end
+
+    def lead_assignments(campaign_id: nil, next_token: nil, per_page: nil, since: nil)
+      client.get("/activity/lead-assignments", camelize_params(
+        campaign_id: campaign_id,
+        next_token: next_token,
+        per_page: per_page,
+        since: since
+      ))
+    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(
+        campaign_id: campaign_id,
+        recipient_email_address: recipient_email_address,
+        assigned_to_email_address: assigned_to_email_address,
+        next_token: next_token,
+        per_page: per_page,
+        since: since
+      ))
+    end
+  end
+end

data/lib/mailshake/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Base
+    attr_reader :client
+
+    UPPERCASE_SUFFIXES = {
+      "id" => "ID",
+      "ids" => "IDs"
+    }.freeze
+
+    def initialize(client = nil)
+      @client = client || Mailshake.client
+    end
+
+    private
+
+    def camelize(key)
+      parts = key.to_s.split('_')
+      return parts[0] if parts.length == 1
+
+      result = parts[0].dup
+      parts[1..].each do |part|
+        if UPPERCASE_SUFFIXES[part]
+          result << UPPERCASE_SUFFIXES[part]
+        else
+          result << part.capitalize
+        end
+      end
+      result
+    end
+
+    def camelize_params(params)
+      params.each_with_object({}) do |(key, value), hash|
+        hash[camelize(key)] = value unless value.nil?
+      end
+    end
+  end
+end

data/lib/mailshake/campaigns.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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))
+    end
+
+    def get(campaign_id:)
+      client.get("/campaigns/get", camelize_params(campaign_id: campaign_id))
+    end
+
+    def create(title:, sender_id: nil)
+      client.post("/campaigns/create", camelize_params(title: title, sender_id: sender_id))
+    end
+
+    def pause(campaign_id:)
+      client.post("/campaigns/pause", camelize_params(campaign_id: campaign_id))
+    end
+
+    def unpause(campaign_id:)
+      client.post("/campaigns/unpause", camelize_params(campaign_id: campaign_id))
+    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))
+    end
+
+    def export_status(status_id:)
+      client.get("/campaigns/export-status", camelize_params(status_id: status_id))
+    end
+  end
+end

data/lib/mailshake/client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Mailshake
+  class Client
+    include HTTParty
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+      validate_configuration!
+    end
+
+    def get(path, params = {})
+      request(:get, path, query: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, body: data.to_json)
+    end
+
+    def me
+      get("/me")
+    end
+
+    private
+
+    def validate_configuration!
+      missing = configuration.missing_credentials
+      raise ConfigurationError, missing unless missing.empty?
+    end
+
+    def request(method, path, options = {})
+      url = "#{configuration.base_url}#{path}"
+      request_options = {
+        headers: auth_headers,
+        timeout: configuration.timeout
+      }
+
+      if options[:query]
+        request_options[:query] = options[:query]
+      end
+
+      if options[:body]
+        request_options[:body] = options[:body]
+        request_options[:headers] = request_options[:headers].merge('Content-Type' => 'application/json')
+      end
+
+      response = self.class.send(method, url, request_options)
+      handle_response(response)
+    end
+
+    def auth_headers
+      credentials = Base64.strict_encode64("#{configuration.api_key}:")
+      {
+        'Authorization' => "Basic #{credentials}",
+        'Accept' => 'application/json'
+      }
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201, 202, 204
+        response.parsed_response
+      when 401
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 404
+        raise NotFoundError.new("Resource not found", response.code, response.body)
+      when 429
+        retry_after = response.headers['retry-after']
+        raise RateLimitError.new("Rate limit exceeded", response.code, response.body, retry_after)
+      when 400, 422
+        parsed = response.parsed_response || {}
+        errors = parsed['errors'] || {}
+        raise ValidationError.new(
+          parsed['message'] || 'Validation failed',
+          response.code,
+          response.body,
+          errors
+        )
+      when 500..599
+        raise APIError.new("Server error", response.code, response.body)
+      else
+        raise APIError.new("Unexpected response", response.code, response.body)
+      end
+    end
+  end
+end

data/lib/mailshake/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    def initialize
+      @base_url = "https://api.mailshake.com/2017-04-01"
+      @timeout = 30
+    end
+
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+
+    def missing_credentials
+      missing = []
+      missing << "api_key" if api_key.nil? || api_key.to_s.empty?
+      missing
+    end
+  end
+end

data/lib/mailshake/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Error < StandardError; end
+
+  class ConfigurationError < Error
+    def initialize(missing_credentials)
+      super("Missing required credentials: #{missing_credentials.join(', ')}")
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code = nil, response_body = nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class ValidationError < APIError
+    attr_reader :errors
+
+    def initialize(message, status_code = nil, response_body = nil, errors = {})
+      super(message, status_code, response_body)
+      @errors = errors
+    end
+  end
+
+  class NotFoundError < APIError
+    def initialize(message = "Resource not found", status_code = 404, response_body = nil)
+      super(message, status_code, response_body)
+    end
+  end
+
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", status_code = 429, response_body = nil, retry_after = nil)
+      super(message, status_code, response_body)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/mailshake/leads.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+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(
+        campaign_id: campaign_id,
+        status: status,
+        assigned_to_email_address: assigned_to_email_address,
+        search: search,
+        next_token: next_token,
+        per_page: per_page
+      ))
+    end
+
+    def get(lead_id: nil, recipient_id: nil, campaign_id: nil, email_address: nil)
+      client.get("/leads/get", camelize_params(
+        lead_id: lead_id,
+        recipient_id: recipient_id,
+        campaign_id: campaign_id,
+        email_address: email_address
+      ))
+    end
+
+    def create(campaign_id:, email_addresses: nil, recipient_ids: nil)
+      client.post("/leads/create", camelize_params(
+        campaign_id: campaign_id,
+        email_addresses: email_addresses,
+        recipient_ids: recipient_ids
+      ))
+    end
+
+    def close(lead_id: nil, campaign_id: nil, email_address: nil, recipient_id: nil, status: nil)
+      client.post("/leads/close", camelize_params(
+        lead_id: lead_id,
+        campaign_id: campaign_id,
+        email_address: email_address,
+        recipient_id: recipient_id,
+        status: status
+      ))
+    end
+
+    def ignore(lead_id: nil, campaign_id: nil, email_address: nil, recipient_id: nil)
+      client.post("/leads/ignore", camelize_params(
+        lead_id: lead_id,
+        campaign_id: campaign_id,
+        email_address: email_address,
+        recipient_id: recipient_id
+      ))
+    end
+
+    def reopen(lead_id: nil, campaign_id: nil, email_address: nil, recipient_id: nil)
+      client.post("/leads/reopen", camelize_params(
+        lead_id: lead_id,
+        campaign_id: campaign_id,
+        email_address: email_address,
+        recipient_id: recipient_id
+      ))
+    end
+  end
+end

data/lib/mailshake/push.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Push < Base
+    def create(target_url:, event:, filter: nil)
+      client.post("/push/create", camelize_params(target_url: target_url, event: event, filter: filter))
+    end
+
+    def delete(target_url:)
+      client.post("/push/delete", camelize_params(target_url: target_url))
+    end
+  end
+end

data/lib/mailshake/recipients.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Recipients < Base
+    def add(campaign_id:, addresses: nil, list_of_emails: nil, csv_data: nil, add_as_new_list: nil, truncate_extra_fields: nil)
+      client.post("/recipients/add", camelize_params(
+        campaign_id: campaign_id,
+        addresses: addresses,
+        list_of_emails: list_of_emails,
+        csv_data: csv_data,
+        add_as_new_list: add_as_new_list,
+        truncate_extra_fields: truncate_extra_fields
+      ))
+    end
+
+    def add_status(status_id:)
+      client.get("/recipients/add-status", camelize_params(status_id: status_id))
+    end
+
+    def list(campaign_id:, filter: nil, search: nil, next_token: nil, per_page: nil)
+      client.get("/recipients/list", camelize_params(
+        campaign_id: campaign_id,
+        filter: filter,
+        search: search,
+        next_token: next_token,
+        per_page: per_page
+      ))
+    end
+
+    def get(recipient_id: nil, campaign_id: nil, email_address: nil)
+      client.get("/recipients/get", camelize_params(
+        recipient_id: recipient_id,
+        campaign_id: campaign_id,
+        email_address: email_address
+      ))
+    end
+
+    def pause(campaign_id:, email_address:)
+      client.post("/recipients/pause", camelize_params(campaign_id: campaign_id, email_address: email_address))
+    end
+
+    def unpause(campaign_id:, email_address:)
+      client.post("/recipients/unpause", camelize_params(campaign_id: campaign_id, email_address: email_address))
+    end
+
+    def unsubscribe(email_addresses:)
+      client.post("/recipients/unsubscribe", camelize_params(email_addresses: email_addresses))
+    end
+  end
+end

data/lib/mailshake/senders.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Senders < Base
+    def list(search: nil, next_token: nil, per_page: nil)
+      client.get("/senders/list", camelize_params(search: search, next_token: next_token, per_page: per_page))
+    end
+  end
+end

data/lib/mailshake/team.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Mailshake
+  class Team < Base
+    def list_members(search: nil, next_token: nil, per_page: nil)
+      client.get("/team/list-members", camelize_params(search: search, next_token: next_token, per_page: per_page))
+    end
+  end
+end

data/lib/mailshake/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailshake
+  VERSION = "0.1.0"
+end