isend 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b77ca55ae43e1aa40d4dfa688b159ac63061d4c5e448e9905a6fcb39e74dc1ae
+  data.tar.gz: 70cd3a62700318fb01464050153e4cf6f774ed84796d54300e51b7c8bcccb4af
+SHA512:
+  metadata.gz: bfa0d7d258258a0c7b6d82f3e16d4d2b13094f2bfce38767831bb300c89df70d404097b13ed26f8fe6fb400a4b96536065441ad79a899a49e5baf58cd0f360c5
+  data.tar.gz: 9855d39bf75487512affd620d6d7556fffb803b668c1b5d80b82f3387793ee3be86e5f0f2df5e83a577bf1e101f72b3ab9d611d7bf5c008e610216ad831789dd

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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] - 2024-01-01
+
+### Added
+- Initial release of the Ruby SDK
+- `ISend::Client` class for sending emails via isend.ai API
+- Support for template-based email sending
+- Custom exception classes for error handling
+- Rails integration examples
+- Comprehensive documentation and examples
+- HTTParty integration for HTTP requests
+- Configuration options including timeout settings
+
+### Features
+- Send emails using template IDs
+- Data mapping for template variables
+- Proper error handling with custom exceptions
+- Easy integration with Rails applications
+- Background job support examples 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 isend.ai
+
+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,213 @@
+# isend.ai Ruby SDK
+
+A simple Ruby SDK for sending emails through isend.ai using various email connectors like AWS SES, SendGrid, Mailgun, and more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'isend'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install isend
+```
+
+## Quick Start
+
+```ruby
+require 'isend'
+
+# Initialize the client
+client = ISend::Client.new('your-api-key-here')
+
+# Send email using template
+email_data = {
+  template_id: 124,
+  to: 'hi@isend.ai',
+  dataMapping: {
+    name: 'ISend'
+  }
+}
+
+response = client.send_email(email_data)
+puts response
+```
+
+## Usage
+
+### Send Email Using Template
+
+```ruby
+email_data = {
+  template_id: 124,
+  to: 'hi@isend.ai',
+  dataMapping: {
+    name: 'ISend'
+  }
+}
+
+response = client.send_email(email_data)
+```
+
+### With Configuration Options
+
+```ruby
+client = ISend::Client.new('your-api-key-here', timeout: 60)
+
+email_data = {
+  template_id: 124,
+  to: 'hi@isend.ai',
+  dataMapping: {
+    name: 'ISend',
+    company: 'Your Company'
+  }
+}
+
+response = client.send_email(email_data)
+```
+
+## API Reference
+
+### ISend::Client
+
+#### Constructor
+```ruby
+ISend::Client.new(api_key, config = {})
+```
+
+**Parameters:**
+- `api_key` (String): Your isend.ai API key
+- `config` (Hash): Additional configuration options
+  - `timeout` (Integer): Request timeout in seconds (default: 30)
+
+#### Methods
+
+##### send_email(email_data)
+Sends an email using the provided template and data.
+
+**Parameters:**
+- `email_data` (Hash): Email data including:
+  - `template_id` (Integer): The template ID to use
+  - `to` (String): Recipient email address
+  - `dataMapping` (Hash): Data mapping for template variables
+
+**Returns:**
+- `Hash`: Response from the API
+
+## Error Handling
+
+The SDK raises custom exceptions for different error types:
+
+```ruby
+begin
+  response = client.send_email({
+    template_id: 124,
+    to: 'hi@isend.ai',
+    dataMapping: {
+      name: 'ISend'
+    }
+  })
+rescue ISend::InvalidArgumentError => e
+  puts "Invalid argument: #{e.message}"
+rescue ISend::ApiError => e
+  puts "API error: #{e.message}"
+rescue ISend::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+### Exception Types
+
+- `ISend::InvalidArgumentError`: Raised when invalid arguments are provided
+- `ISend::ApiError`: Raised when the API request fails
+- `ISend::Error`: Base exception class for all SDK errors
+
+## Rails Integration
+
+### In Rails Application
+
+Add to your Gemfile:
+
+```ruby
+gem 'isend'
+```
+
+Create an initializer (`config/initializers/isend.rb`):
+
+```ruby
+ISEND_CLIENT = ISend::Client.new(ENV['ISEND_API_KEY'])
+```
+
+Use in your controllers or models:
+
+```ruby
+class UserMailer
+  def self.send_welcome_email(user)
+    email_data = {
+      template_id: 124,
+      to: user.email,
+      dataMapping: {
+        name: user.name,
+        company: user.company
+      }
+    }
+    
+    ISEND_CLIENT.send_email(email_data)
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+class EmailJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id, template_id)
+    user = User.find(user_id)
+    
+    email_data = {
+      template_id: template_id,
+      to: user.email,
+      dataMapping: {
+        name: user.name
+      }
+    }
+    
+    ISEND_CLIENT.send_email(email_data)
+  end
+end
+```
+
+## Examples
+
+See the `examples/` directory for complete usage examples.
+
+## Requirements
+
+- Ruby 2.0 or higher
+- HTTParty gem for HTTP requests
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/isend-ai/ruby-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/rails_integration.rb

@@ -0,0 +1,73 @@
+# Rails Integration Example
+# This file shows how to integrate the ISend SDK with a Rails application
+
+# In config/initializers/isend.rb
+ISEND_CLIENT = ISend::Client.new(ENV['ISEND_API_KEY'])
+
+# In app/models/user_mailer.rb
+class UserMailer
+  def self.send_welcome_email(user)
+    email_data = {
+      template_id: 124,
+      to: user.email,
+      dataMapping: {
+        name: user.name,
+        company: user.company || 'Your Company'
+      }
+    }
+    
+    ISEND_CLIENT.send_email(email_data)
+  end
+  
+  def self.send_password_reset(user, reset_token)
+    email_data = {
+      template_id: 125,
+      to: user.email,
+      dataMapping: {
+        name: user.name,
+        reset_url: "#{ENV['APP_URL']}/reset-password?token=#{reset_token}"
+      }
+    }
+    
+    ISEND_CLIENT.send_email(email_data)
+  end
+end
+
+# In app/jobs/email_job.rb
+class EmailJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id, template_id, data_mapping = {})
+    user = User.find(user_id)
+    
+    email_data = {
+      template_id: template_id,
+      to: user.email,
+      dataMapping: data_mapping.merge({
+        name: user.name,
+        email: user.email
+      })
+    }
+    
+    ISEND_CLIENT.send_email(email_data)
+  end
+end
+
+# Usage in controllers
+class UsersController < ApplicationController
+  def create
+    @user = User.new(user_params)
+    
+    if @user.save
+      # Send welcome email
+      UserMailer.send_welcome_email(@user)
+      
+      # Or use background job
+      EmailJob.perform_later(@user.id, 124, { company: 'Your Company' })
+      
+      redirect_to @user, notice: 'User created successfully!'
+    else
+      render :new
+    end
+  end
+end 

data/examples/send_email.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/isend'
+
+# Initialize the client with your API key
+client = ISend::Client.new('your-api-key-here')
+
+# Example: Send email using template
+begin
+  email_data = {
+    template_id: 124,
+    to: 'hi@isend.ai',
+    dataMapping: {
+      name: 'ISend'
+    }
+  }
+  
+  response = client.send_email(email_data)
+  
+  puts "Email sent successfully!"
+  puts response
+rescue ISend::InvalidArgumentError => e
+  puts "Invalid argument: #{e.message}"
+rescue ISend::ApiError => e
+  puts "API error: #{e.message}"
+rescue ISend::Error => e
+  puts "General error: #{e.message}"
+end 

data/lib/isend/client.rb

@@ -0,0 +1,84 @@
+require 'httparty'
+require 'json'
+
+module ISend
+  class Client
+    include HTTParty
+    
+    API_BASE_URL = 'https://www.isend.ai/api'
+    
+    attr_reader :api_key, :timeout
+    
+    # Create a new ISend::Client instance
+    #
+    # @param api_key [String] Your isend.ai API key
+    # @param config [Hash] Additional configuration options
+    # @option config [Integer] :timeout (30) Request timeout in seconds
+    # @raise [ISend::InvalidArgumentError] if API key is empty
+    def initialize(api_key, config = {})
+      if api_key.nil? || api_key.strip.empty?
+        raise ISend::InvalidArgumentError, 'API key is required'
+      end
+      
+      @api_key = api_key.strip
+      @timeout = config[:timeout] || 30
+      
+      # Configure HTTParty
+      self.class.base_uri API_BASE_URL
+      self.class.default_timeout @timeout
+      self.class.headers({
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type' => 'application/json',
+        'User-Agent' => "isend-ai-ruby-sdk/#{ISend::VERSION}"
+      })
+    end
+    
+    # Send an email using isend.ai
+    #
+    # @param email_data [Hash] Email data including template_id, to, dataMapping, etc.
+    # @option email_data [Integer] :template_id The template ID to use
+    # @option email_data [String] :to Recipient email address
+    # @option email_data [Hash] :dataMapping Data mapping for template variables
+    # @return [Hash] Response from the API
+    # @raise [ISend::ApiError] if the API request fails
+    def send_email(email_data)
+      validate_email_data(email_data)
+      
+      response = self.class.post('/send-email', {
+        body: email_data.to_json,
+        headers: { 'Content-Type' => 'application/json' }
+      })
+      
+      handle_response(response)
+    end
+    
+    private
+    
+    def validate_email_data(email_data)
+      unless email_data.is_a?(Hash)
+        raise ISend::InvalidArgumentError, 'Email data must be a hash'
+      end
+      
+      unless email_data[:template_id]
+        raise ISend::InvalidArgumentError, 'template_id is required'
+      end
+      
+      unless email_data[:to]
+        raise ISend::InvalidArgumentError, 'to email address is required'
+      end
+    end
+    
+    def handle_response(response)
+      case response.code
+      when 200..299
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise ISend::ApiError, "Invalid JSON response: #{e.message}"
+        end
+      else
+        raise ISend::ApiError, "HTTP error #{response.code}: #{response.body}"
+      end
+    end
+  end
+end 

data/lib/isend/version.rb

@@ -0,0 +1,3 @@
+module ISend
+  VERSION = "1.0.0"
+end 

data/lib/isend.rb

@@ -0,0 +1,11 @@
+require 'httparty'
+require 'json'
+
+require_relative 'isend/client'
+require_relative 'isend/version'
+
+module ISend
+  class Error < StandardError; end
+  class InvalidArgumentError < Error; end
+  class ApiError < Error; end
+end 

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: isend
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- isend.ai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: A simple Ruby SDK for sending emails through isend.ai using various email
+  connectors like AWS SES, SendGrid, Mailgun, and more.
+email:
+- support@isend.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- examples/rails_integration.rb
+- examples/send_email.rb
+- lib/isend.rb
+- lib/isend/client.rb
+- lib/isend/version.rb
+homepage: https://github.com/isend-ai/ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/isend-ai/ruby-sdk
+  source_code_uri: https://github.com/isend-ai/ruby-sdk
+  changelog_uri: https://github.com/isend-ai/ruby-sdk/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for isend.ai - Send emails easily using email connectors like SES,
+  SendGrid, and more
+test_files: []