Ruby SDK for the Poodle's email sending API.
Add this line to your application's Gemfile:
gem 'poodle-ruby'
And then execute:
bundle install
Or install it yourself as:
gem install poodle-ruby
require 'poodle'
# Initialize the client
client = Poodle::Client.new(api_key: 'your_api_key')
# Send an email
response = client.send(
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Hello from Poodle!',
html: '<h1>Hello World!</h1><p>This email was sent using Poodle.</p>'
)
if response.success?
puts "Email sent successfully!"
else
puts "Failed to send email: #{response.message}"
end
Set your API key in one of these ways:
# 1. Pass directly to client
client = Poodle::Client.new(api_key: 'your_api_key')
# 2. Use environment variable
ENV['POODLE_API_KEY'] = 'your_api_key'
client = Poodle::Client.new
# 3. Use configuration object
config = Poodle::Configuration.new(
api_key: 'your_api_key',
timeout: 30,
debug: true
)
client = Poodle::Client.new(config)
| Variable | Description | Default |
|---|---|---|
POODLE_API_KEY | Your Poodle API key | Required |
POODLE_BASE_URL | API base URL | https://api.usepoodle.com |
POODLE_TIMEOUT | Request timeout in seconds | 30 |
POODLE_CONNECT_TIMEOUT | Connection timeout in seconds | 10 |
POODLE_DEBUG | Enable debug logging | false |
# HTML email
response = client.send_html(
from: 'newsletter@example.com',
to: 'subscriber@example.com',
subject: 'Weekly Newsletter',
html: '<h1>Newsletter</h1><p>Your weekly update...</p>'
)
# Plain text email
response = client.send_text(
from: 'notifications@example.com',
to: 'user@example.com',
subject: 'Account Update',
text: 'Your account has been updated successfully.'
)
# Multipart email (HTML + Text)
response = client.send(
from: 'support@example.com',
to: 'customer@example.com',
subject: 'Welcome!',
html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
text: 'Welcome! Thanks for joining us.'
)
# Create an Email object for reusability and validation
email = Poodle::Email.new(
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Important Update',
html: '<h1>Update</h1><p>Please read this important update.</p>',
text: 'Update: Please read this important update.'
)
# Check email properties
puts "Multipart email: #{email.multipart?}"
puts "Content size: #{email.content_size} bytes"
# Send the email
response = client.send_email(email)
# Send emails with both HTML and text content for maximum compatibility
response = client.send(
from: 'newsletter@example.com',
to: 'subscriber@example.com',
subject: 'Weekly Newsletter',
html: '<h1>Newsletter</h1><p>This week\'s updates...</p>',
text: 'Newsletter\n\nThis week\'s updates...'
)
The Poodle SDK provides seamless Rails integration with automatic configuration and helpful rake tasks.
Add to your Rails application's Gemfile:
gem 'poodle-ruby'
Create an initializer or let Poodle auto-configure:
# config/initializers/poodle.rb
Poodle::Rails.configure do |config|
config.api_key = Rails.application.credentials.poodle_api_key
config.debug = Rails.env.development?
end
Or use environment variables:
# .env or environment
POODLE_API_KEY=your_api_key_here
class NotificationController < ApplicationController
def send_welcome_email
response = Poodle::Rails.client.send(
from: "welcome@example.com",
to: params[:email],
subject: "Welcome!",
html: render_to_string("welcome_email")
)
if response.success?
render json: { status: "sent" }
else
render json: { error: response.message }, status: :unprocessable_entity
end
end
end
# Check configuration
rake poodle:config
# Test connection
rake poodle:test
# Send test email
rake poodle:send_test[recipient@example.com]
# Generate initializer
rake poodle:install
The SDK includes comprehensive testing utilities for easy testing in your applications.
# spec/spec_helper.rb or spec/rails_helper.rb
require 'poodle'
RSpec.configure do |config|
config.include Poodle::TestHelpers
config.before(:each) do
Poodle.test_mode!
end
config.after(:each) do
Poodle.clear_deliveries
end
end
it "sends welcome email" do
expect {
UserMailer.send_welcome(user)
}.to change { Poodle.deliveries.count }.by(1)
email = Poodle.last_delivery
expect(email[:to]).to eq(user.email)
expect(email[:subject]).to include("Welcome")
expect(email[:html]).to include(user.name)
end
it "sends notification emails" do
service.send_notifications
assert_email_sent(3)
assert_email_sent_to("admin@example.com")
assert_email_sent_with_subject("Alert")
end
begin
response = client.send(email_data)
puts "Email sent!" if response.success?
rescue Poodle::ValidationError => e
puts "Validation failed: #{e.message}"
e.errors.each do |field, messages|
puts "#{field}: #{messages.join(', ')}"
end
rescue Poodle::AuthenticationError => e
puts "Authentication failed: #{e.message}"
rescue Poodle::RateLimitError => e
puts "Rate limited. Retry after: #{e.retry_after} seconds"
rescue Poodle::PaymentError => e
puts "Payment required: #{e.message}"
puts "Upgrade at: #{e.upgrade_url}"
rescue Poodle::ForbiddenError => e
puts "Access forbidden: #{e.message}"
rescue Poodle::NetworkError => e
puts "Network error: #{e.message}"
rescue Poodle::ServerError => e
puts "Server error: #{e.message}"
rescue Poodle::Error => e
puts "Poodle error: #{e.message}"
end
def send_with_retry(client, email_data, max_retries: 3)
retries = 0
begin
client.send(email_data)
rescue Poodle::RateLimitError => e
if retries < max_retries && e.retry_after
retries += 1
sleep(e.retry_after)
retry
else
raise
end
rescue Poodle::NetworkError, Poodle::ServerError => e
if retries < max_retries
retries += 1
sleep(2 ** retries) # Exponential backoff
retry
else
raise
end
end
end
Poodle::Client.new(config_or_api_key, **options)Creates a new Poodle client.
Parameters:
config_or_api_key - Configuration object, API key string, or nil**options - Additional options (base_url, timeout, debug, etc.)client.send(from:, to:, subject:, html: nil, text: nil)Sends an email with the specified parameters.
client.send_email(email)Sends an Email object.
client.send_html(from:, to:, subject:, html:)Sends an HTML-only email.
client.send_text(from:, to:, subject:, text:)Sends a text-only email.
Poodle::Email.new(from:, to:, subject:, html: nil, text: nil)Creates a new Email object with validation.
Methods:
#html? - Returns true if HTML content is present#text? - Returns true if text content is present#multipart? - Returns true if both HTML and text are present#content_size - Returns total content size in bytes#to_h - Converts to hash for API requests#success? - Returns true if email was successfully queued#failed? - Returns true if email sending failed#message - Response message from API#data - Additional response dataPoodle::Configuration.new(**options)Creates a new configuration object.
Options:
api_key - Your Poodle API keybase_url - API base URLtimeout - Request timeout in secondsconnect_timeout - Connection timeout in secondsdebug - Enable debug logginghttp_options - Additional HTTP client options| Error Class | Description | HTTP Status |
|---|---|---|
Poodle::ValidationError | Invalid request data | 400, 422 |
Poodle::AuthenticationError | Invalid API key | 401 |
Poodle::PaymentError | Payment required | 402 |
Poodle::ForbiddenError | Access forbidden | 403 |
Poodle::RateLimitError | Rate limit exceeded | 429 |
Poodle::ServerError | Server error | 5xx |
Poodle::NetworkError | Network/connection error | Various |
All errors inherit from Poodle::Error which provides:
#message - Error message#context - Additional error context#status_code - HTTP status code (if applicable)After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rspec 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 the created tag, and push the .gem file to rubygems.org.
Contributions are welcome! Please read our Contributing Guide for details on the process for submitting pull requests and our Code of Conduct.
The gem is available as open source under the terms of the MIT License.
FAQs
Unknown package
We found that poodle-ruby demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.
Security News
CISA’s 2025 draft SBOM guidance adds new fields like hashes, licenses, and tool metadata to make software inventories more actionable.
Security News
A clarification on our recent research investigating 60 malicious Ruby gems.