Pylon API Ruby Client

A Ruby client for the Pylon API.

Installation

Add this line to your application's Gemfile:

gem 'pylon-api'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install pylon-api

Usage

First, initialize a client with your API key:

require 'pylon'

client = Pylon::Client.new(api_key: 'your_api_key')

# Enable debug mode to see request/response details
client = Pylon::Client.new(api_key: 'your_api_key', debug: true)

Object Model

The client returns Ruby objects that provide direct access to attributes through method calls. For example:

# Instead of accessing attributes like a hash: issue['title']
# You can use object methods: issue.title

# Collections are enumerable and can be iterated over
issues.each do |issue|
  puts "#{issue.id}: #{issue.title} (#{issue.status})"
end

Examples

Current User

# Get current user details
me = client.get_current_user
puts "Logged in as: #{me.email} (#{me.name})"

Accounts

# List accounts with pagination
accounts = client.list_accounts(page: 1, per_page: 20)
accounts.each do |account|
  puts "#{account.id}: #{account.name}"
end

# Get a specific account
account = client.get_account('account_id')
puts "Account name: #{account.name}"

# Access the raw response if needed
response = account._response

Issues

# List issues (requires time range, max 365 days)
start_time = Time.now.utc - 86400 # 24 hours ago
end_time = Time.now.utc

issues = client.list_issues(
  start_time: start_time.iso8601,
  end_time: end_time.iso8601,
  page: 1,
  per_page: 20
)

# Iterate through issues
issues.each do |issue|
  puts "#{issue.id}: #{issue.title} (#{issue.state})"
end

# Create an issue (title and body_html are required by the API)
issue = client.create_issue(
  title: 'New Issue',
  body_html: '<p>Issue description</p>',
  requester_email: 'customer@example.com'
)

# Access issue properties directly
puts "Created issue #{issue.id}: #{issue.title}"

Teams

# List teams
teams = client.list_teams(page: 1, per_page: 20)

# Create a team
team = client.create_team(name: 'Engineering')

# Get a specific team
team = client.get_team('team_id')

Users

# List users
users = client.list_users(page: 1, per_page: 20)

# Create a user
user = client.create_user(
  email: 'user@example.com',
  name: 'New User'
)

# Get a specific user
user = client.get_user('user_id')

# Update a user
updated_user = client.update_user('user_id', { name: 'Updated Name' })

Tags

# List tags
tags = client.list_tags(page: 1, per_page: 20)

# Create a tag
tag = client.create_tag(
  name: 'bug',
  color: '#ff0000'
)

Ticket Forms

# List ticket forms
forms = client.list_ticket_forms(page: 1, per_page: 20)

# Create a ticket form
form = client.create_ticket_form(
  name: 'Bug Report',
  fields: [
    { name: 'severity', type: 'select' }
  ]
)

Attachments

# Create an attachment from raw content
attachment = client.create_attachment(file_content)

# Create an attachment from a file
file = File.open('document.pdf', 'rb')
attachment = client.create_attachment(file)

# Create an attachment from a URL with description
attachment = client.create_attachment(nil, 
  file_url: 'https://example.com/document.pdf',
  description: 'Important document'
)

Email Suppressions

Pylon stops sending email to an address once it hard bounces or is suppressed manually. Use these methods to check and clear suppressions.

# Check whether a single address is suppressed
suppressions = client.list_email_suppressions(email: 'user@example.com')

if suppressions.size.zero?
  puts 'not suppressed'
else
  suppression = suppressions.first
  puts "#{suppression.email} suppressed (#{suppression.reason}) at #{suppression.created_at}"
  puts suppression.bounce_details if suppression.bounce_details
end

# List suppressions, most recent first, using the API's cursor pagination
page = client.list_email_suppressions(limit: 100)
pagination = page._response.body['pagination']
next_page = client.list_email_suppressions(cursor: pagination['cursor']) if pagination['has_next_page']

# Remove a suppression so Pylon resumes sending to the address
client.delete_email_suppression(suppression.id)

Error Handling

The client will raise different types of errors based on the API response:

• Pylon::AuthenticationError - When the API key is invalid
• Pylon::ResourceNotFoundError - When the requested resource is not found
• Pylon::ValidationError - When the request parameters are invalid
• Pylon::ApiError - For other API errors

Example:

begin
  client.get_issue('non_existent_id')
rescue Pylon::ResourceNotFoundError => e
  puts "Issue not found: #{e.message}"
rescue Pylon::ApiError => e
  puts "API error: #{e.message}"
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install.

Testing Locally

To test the gem locally:

1. Build and install the gem:

gem build pylon-api.gemspec
gem install ./pylon-api-*.gem

2. Create a test script:

require 'pylon'

client = Pylon::Client.new(api_key: ENV['PYLON_API_KEY'], debug: true)

begin
  me = client.get_current_user
  puts "Successfully connected as: #{me['email']}"
rescue => e
  puts "Error: #{e.message}"
end

3. Run with your API key:

PYLON_API_KEY=your_api_key_here ruby test.rb

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the MIT License.