Convertkit Ruby Client

A Ruby toolkit for Convertkit API.

Installation

Add this line to your application's Gemfile:

gem 'convertkit-ruby', require: 'convertkit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install convertkit-ruby

Authentication

For private integrations, use your personal API_KEY and API_SECRET found in your account settings.

require "dotenv"
Dotenv.load(".env.local")

Convertkit.configure do |config|
  config.api_secret = ENV["API_SECRET"]
  config.api_key = ENV["API_KEY"]
end

client = Convertkit::Client.new

Usage

Calls for Convertkit API v3 are relative to the url http://api.convertkit.com/v3.

API actions are available as methods on the client object. Currently, the Convertkit client has the following methods:

Action	Method
Get account information	`#account`
List subscribers	`#subscribers(options = {})`
Fetch a subscriber	`#subscriber(subscriber_id)`
List sequences/courses	`#sequences`
Add subscriber to sequence	`#add_subscriber_to_sequence(sequence_id, email, options = {})`
List tags	`#tags`
Add subscriber to tag	`#add_subscriber_to_tag(tag_id, email, options = {})`
Remove tag from a subscriber	`#remove_tag_from_subscriber(subscriber_id, tag_id)`
List forms	`#forms`
Add subscriber to form	`#add_subscriber_to_form(form_id, email, options = {})`
Unsubscribe	`#unsubscribe(email)`

Note: We do not have complete API coverage yet. If we are missing an API method that you need to use in your application, please file an issue and/or open a pull request.

See the official API documentation for a complete API reference.

Use Cases

Here are some common use cases for the Convertkit v3 API client.

First configure the convertkit-ruby gem with your API_KEY and API_SECRET, and initialize a new client. After that, you can fetch data from your account.

List subscribers

List all subscribers added to your account on or after a specific date.

response = client.subscribers(from: "2016-03-01")
# => <Faraday::Response ...>

response.status
# => 200

Fetching subscriber data

Subscribers can be looked up by their subscriber_id.

response = client.subscriber("17682009")
# => <Faraday::Response ...>

response.status
# => 200

Development

After checking out the repo, run bin/setup to install dependencies. Then, copy .env.local.sample to .env.local and substitute your own real values from your account. Finally, 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Atomoworks/convertkit-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Fork it ( https://github.com/Atomoworks/convertkit-ruby/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

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

maximadeka / convertkit-ruby

readme