Ruby API Pack ActiveCampaign

Repository Snapshot

Field	Value
Project team	`project-ruby`
Repository role	ActiveCampaign API client
Package/artifact	`ruby_api_pack_active_campaign`
Current version/status	0.2.0

Standard Workflow

Read AGENTS.md, then the agent-specific guide for the task.
Check TODO.md and ROADMAP.md for current scope.
Make the smallest repo-local change that satisfies the task.
Run bundle exec rspec, bundle exec rubocop, and gem build ruby_api_pack_active_campaign.gemspec when validation is required or practical.
Update docs and changelog history only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide	Path
Agent rules	AGENTS.md
Claude Code	CLAUDE.md
Codex	CODEX.md
Copilot	COPILOT.md
Jules	JULES.md
Roadmap	ROADMAP.md
Todo	TODO.md
Changelog	CHANGELOG.md
Security	SECURITY.md
Code of Conduct	CODE_OF_CONDUCT.md
Contributing	CONTRIBUTING.md

ruby_api_pack_active_campaign is a Ruby client gem for the ActiveCampaign API. It centralizes ActiveCampaign configuration, HTTP connection handling, response parsing, and contact-oriented API helpers so Ruby and Rails applications can consume ActiveCampaign without duplicating low-level request code.

Source of Truth

The gem's public behavior is defined by its configuration object, connection wrapper, contact API helpers, and specs. Keep those surfaces aligned whenever an ActiveCampaign endpoint or request shape changes.

Layer	Path	Rule
Gem entry point	`lib/ruby_api_pack_active_campaign.rb`	Loads configuration, connection, and API helper surfaces
Configuration	`lib/ruby_api_pack_active_campaign/configuration.rb`	Owns ActiveCampaign base URL and API token settings
Connection wrapper	`lib/ruby_api_pack_active_campaign/connection/ac_connect.rb`	Centralizes HTTParty requests, headers, JSON parsing, and API errors
Contact API helpers	`lib/ruby_api_pack_active_campaign/api/ac_contacts.rb`	Public contact, automation, import, activity, note, and related-resource helpers
Version	`lib/ruby_api_pack_active_campaign/version.rb`	Gem release version
Specs	`spec/`	Contract and regression coverage for configuration, connection, and API helpers

After behavior changes, run:

bundle exec rspec
bundle exec rubocop
gem build ruby_api_pack_active_campaign.gemspec

What This Gem Owns

ActiveCampaign API configuration through RubyApiPackActiveCampaign.configure
HTTParty-based GET, POST, PUT, and DELETE request helpers
ActiveCampaign contact helper methods under RubyApiPackActiveCampaign::Api::AcContacts
JSON response parsing and raised errors for unsuccessful API responses
RSpec coverage for connection behavior and API helper delegation

What This Gem Does Not Own

ActiveCampaign account setup, billing, lists, automations, or dashboard configuration
Host application models, persistence, background jobs, or authorization
User-facing Rails controllers or UI components
Storage of production credentials or API tokens
A complete wrapper for every ActiveCampaign endpoint

Installation

Add the gem to your application's Gemfile:

gem "ruby_api_pack_active_campaign"

Install dependencies:

bundle install

Or install the gem directly:

gem install ruby_api_pack_active_campaign

Configuration

Configure the ActiveCampaign API URL and token before calling API helpers. In a Rails application, this typically belongs in an initializer.

# config/initializers/ruby_api_pack_active_campaign.rb
RubyApiPackActiveCampaign.configure do |config|
  config.ac_api_url = ENV.fetch("AC_API_URL")
  config.ac_api_token = ENV.fetch("AC_API_TOKEN")
end

ac_api_url should include the API version path, for example:

https://youraccountname.api-us1.com/api/3

Do not commit real ActiveCampaign API tokens. Use Rails credentials, encrypted environment management, or your deployment platform's secret manager.

Contact Usage

Require the gem and call contact helpers through RubyApiPackActiveCampaign::Api::AcContacts.

require "ruby_api_pack_active_campaign"

RubyApiPackActiveCampaign.configure do |config|
  config.ac_api_url = ENV.fetch("AC_API_URL")
  config.ac_api_token = ENV.fetch("AC_API_TOKEN")
end

contacts = RubyApiPackActiveCampaign::Api::AcContacts.contact_list
contact = RubyApiPackActiveCampaign::Api::AcContacts.contact_by_id(123)

Create or sync contacts by passing request bodies that match ActiveCampaign's API contract:

RubyApiPackActiveCampaign::Api::AcContacts.create_contact(
  contact: {
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Example"
  }
)

RubyApiPackActiveCampaign::Api::AcContacts.sync_contact(
  contact: {
    email: "jane@example.com",
    firstName: "Jane"
  }
)

Public API Helpers

The current public helper surface is contact-focused:

Method	ActiveCampaign path
`contact_list`	`GET /contacts`
`contact_by_id(contact_id)`	`GET /contacts/:contact_id`
`create_contact(contact_params)`	`POST /contacts`
`sync_contact(contact_params)`	`POST /contact/sync`
`update_contact(contact_id, contact_params)`	`PUT /contacts/:contact_id`
`delete_contact(contact_id)`	`DELETE /contacts/:contact_id`
`update_contact_list_status(contact_list_params)`	`POST /contactLists`
`list_automations(contact_id)`	`GET /contacts/:contact_id/contactAutomations`
`retrieve_contact_score(contact_id)`	`GET /contacts/:contact_id/scoreValues`
`bulk_import_contacts(import_params)`	`POST /import/bulk_import`
`bulk_import_status_list`	`GET /import/bulk_import`
`bulk_import_status_info`	`GET /import/info`
`list_contact_activities`	`GET /activities`
`retrieve_bounce_logs(contact_id)`	`GET /contacts/:contact_id/bounceLogs`
`retrieve_contact_data(contact_id)`	`GET /contacts/:contact_id/contactData`
`retrieve_contact_goals(contact_id)`	`GET /contacts/:contact_id/contactGoals`
`retrieve_contact_list_memberships(contact_id)`	`GET /contacts/:contact_id/contactLists`
`retrieve_contact_logs(contact_id)`	`GET /contacts/:contact_id/contactLogs`
`retrieve_contact_deals(contact_id)`	`GET /contacts/:contact_id/deals`
`retrieve_contact_field_values(contact_id)`	`GET /contacts/:contact_id/fieldValues`
`retrieve_contact_geo_ips(contact_id)`	`GET /contacts/:contact_id/geoIps`
`retrieve_geo_ip_address(geo_address_id)`	`GET /geoIps/:geo_address_id/geoAddress`
`retrieve_contact_notes(contact_id)`	`GET /contacts/:contact_id/notes`
`list_all_notes`	`GET /notes`
`retrieve_contact_organization(contact_id)`	`GET /contacts/:contact_id/organization`
`retrieve_contact_plus_append(contact_id)`	`GET /contacts/:contact_id/plusAppend`
`retrieve_tracking_logs(contact_id)`	`GET /contacts/:contact_id/trackingLogs`
`retrieve_account_contacts(contact_id)`	`GET /contacts/:contact_id/accountContacts`
`retrieve_automation_entry_counts(contact_id)`	`GET /contacts/:contact_id/automationEntryCounts`

Error Handling

Successful responses are parsed from JSON and returned as Ruby hashes. Non-2xx responses raise an error with the HTTP status and response body. Invalid JSON responses raise a parsing error.

Handle these errors at your application boundary so API failures do not expose tokens, request bodies, or sensitive contact data in logs.

Development

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Run style checks:

bundle exec rubocop

Build the gem locally:

gem build ruby_api_pack_active_campaign.gemspec

Documentation and AI Guides

This repository follows the PHCDevworks documentation model used across the Spectre and Rails/Ruby workspaces:

AGENTS.md defines shared AI boundaries.
CLAUDE.md, CODEX.md, COPILOT.md, and JULES.md define agent-specific working rules.
.github/copilot-instructions.md and .github/codex-instructions.md provide GitHub-integrated assistant guidance.
CHANGELOG.md, ROADMAP.md, and TODO.md keep release and planning context visible.

Contributing

See CONTRIBUTING.md for setup, coding standards, pull request expectations, and release hygiene.

Security

Please do not report vulnerabilities through public issues. Follow SECURITY.md for responsible disclosure.

License

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