This library is designed to help ruby/rails based applications communicate with the publicly available REST API for ActiveCampaign. It also supports a lot of functionality which is currently undocumented in the REST API.
If you are unfamiliar with the ActiveCampaign REST API, you should first read the documentation located at https://developers.activecampaign.com/reference.
Add this line to your application's Gemfile:
gem 'active_campaign_wrapper'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install active_campaign_wrapper
- Initialize
- Tags
- Lists
- List Groups
- Contacts
- Contact Tags
- Contact Automations
- Contact Score Values
- Email Activities
- Custom Fields
- Custom Field Options
- Custom Field Values
- Users
- Groups
- Templates
- Task Types
You can specify your Endpoint URL and API token in a config file looking like this.
ActiveCampaignWrapper.config do |config|
config.endpoint_url = 'your-url'
config.api_token = 'your-token'
end
and then initialize the client like
client = ActiveCampaignWrapper::Client.new
OR
You can pass the Endpoint URL and API token directly to the client.
client = ActiveCampaignWrapper::Client.new({
endpoint_url: 'your-url',
api_token: 'your-token'
})
Tags - Api Reference
client.tags.create({
tag: 'Tag Name',
tag_type: 'contact',
description: 'Tag description'
})
BODY PARAMS
- tag (string) : Name of the new tag
- tag_type (string): Tag-type of the new tag. Possible Values: template, contact.
- description (string): Description of the new tag
client.tags.find(tag_id)
client.tags.update(tag_id, {
tag: 'Updated Tag Name'
})
client.tags.delete(tag_id)
client.tags.all
QUERY PARAMS (Optional)
- search (string): Filter by name of tag(s)
Lists - Api Reference
client.lists.create({
name: 'New List',
stringid: 'new-list',
sender_url:'https://workytical.com',
sender_reminder: 'You are getting this notification as you have subscribed to our list.'
})
BODY PARAMS
- name* (string): Name of the list to create
- stringid* (string): URL-safe list name. Example: 'list-name-sample'
- sender_url* (string): The website URL this list is for.
- sender_reminder* (string): A reminder for your contacts as to why they are on this list and you are messaging them.
- send_last_broadcast (boolean): Boolean value indicating whether or not to send the last sent campaign to this list to a new subscriber upon subscribing. 1 = yes, 0 = no
- carboncopy (string): Comma-separated list of email addresses to send a copy of all mailings to upon send
- subscription_notify (string): Comma-separated list of email addresses to notify when a new subscriber joins this list.
- unsubscription_notify (string): Comma-separated list of email addresses to notify when a subscriber unsubscribes from this list.
- user (integer): User Id of the list owner. A list owner is able to control campaign branding. A property of list.userid also exists on this object; both properties map to the same list owner field and are being maintained in the response object for backward compatibility. If you post values for both list.user and list.userid, the value of list.user will be used.
client.lists.find(list_id)
client.lists.update(list_id, {
name: 'Updated List Name'
})
client.lists.delete(list_id)
client.lists.all
QUERY PARAMS (Optional)
- filters[name] (string): Filter by the name of the list.
List Groups - Api Reference
client.list_groups.create({
listid: list_id,
groupid: group_id
})
BODY PARAMS
- listid* (integer): ID of the list
- groupid* (integer): ID of the group that list should be associated with
client.list_groups.find(list_group_id)
client.list_groups.delete(list_group_id)
client.list_groups.all
Contacts - Api Reference
client.contacts.create({
email: 'contact@email.com',
first_name:'first',
last_name: 'last'
})
BODY PARAMS
- email* (string): Email address of the new contact. Example: 'test@example.com'
- first_name (string): First name of the new contact.
- last_name (string): Last name of the new contact.
- phone (integer): Phone number of the contact.
- field_values (array): Array of contact's custom field values [{field, value}]
client.contacts.sync({
email: 'contact@email.com',
first_name:'first',
last_name: 'last'
})
client.contacts.update_list_status({
list: list_id,
contact: contact_id,
status: 1
})
BODY PARAMS
-
list* (string/integer):ID of the list to subscribe the contact to
-
contact* (string/integer): ID of the contact to subscribe to the list
-
status* (string/integer): Possible Values: -1..3
- -1 Any
- 0 Unconfirmed
- 1 Active
- 2 Unsubscribed
- 3 Bounced
Set to "1" to subscribe the contact to the list. Set to "2" to unsubscribe the contact from the list. WARNING: If you change a status from unsubscribed to active, you can re-subscribe a contact to a list from which they had manually unsubscribed.
-
sourceid (integer): Set to "4" when re-subscribing a contact to a list
client.contacts.find(contact_id)
client.contacts.update(contact_id, {
first_name: 'Updated Contact Name'
})
client.contacts.delete(contact_id)
client.contacts.all
QUERY PARAMS (Optional)
- ids (string): Filter contacts by ID.
- email (string): Email address of the contact you want to get
- email_like (string): Filter contacts that contain the given value in the email address
- exclude (integer): Exclude from the response the contact with the given ID
- formid (integer): Filter contacts associated with the given form
- id_greater (integer): Only include contacts with an ID greater than the given ID
- id_less (integer): Only include contacts with an ID less than the given ID
- listid (string): Filter contacts associated with the given list
- search (string): Filter contacts that match the given value in the contact names, organization, phone or email
- segmentid (integer): Return only contacts that match a list segment (this param initially returns segment information, when it is run a second time it will return contacts that match the segment)
- seriesid (integer): Filter contacts associated with the given automation
- tagid (integer): Filter contacts associated with the given tag
- filters[created_before] (date) Filter contacts that were created prior to this date
- filters[created_after] (date): Filter contacts that were created after this date
- filters[updated_before] (date): Filter contacts that were updated before this date
- filters[updated_after] (date): Filter contacts that were updated after this date
- waitid (integer): Filter by contacts in the wait queue of an automation block
- orders[cdate] (string): Order contacts by creation date
- orders[email] (string): Order contacts by email
- orders[first_name] (string): Order contacts by first name
- orders[last_name] (string): Order contacts by last name
- orders[name] (string): Order contacts by full name
- orders[score] (string): Order contacts by score
- in_group_lists (string): Set this to "true" in order to return only contacts that the current user has permissions to see.
client.contacts.bulk_import({
contacts: [
{
email: 'someone@somewhere.com',
first_name: 'Jane',
last_name: 'Doe',
phone: '123-456-7890',
customer_acct_name: 'ActiveCampaign',
tags: [
'dictumst aliquam augue quam sollicitudin rutrum'
]
}
],
callback: {
url: "www.your_web_server.com",
request_type: "POST",
detailed_results: "true",
params: [
{ "key": "", "value": "" }
],
headers: [
{ "key": "", "value": "" }
]
}
})
BODY PARAMS
- contacts* (array of objects): An array of objects containing information about a single contact. Up to 250 contacts may be included in a single request. The suggested minimum number of contacts is 10. If less than that, then contact/sync api request should be used.
- callback (object): Callback function to notify users when an import is complete.
- url (string): The URL endpoint which the importer will make a request to once the import has completed.
- request_type (string): Can be set to either “GET” or “POST”. Determines the type of HTTP request which will be sent to the specified endpoint.
- detailed_results (string): When set to “true” and the requestType parameter is set to “POST”, the callback will include the number of successes and failures in the originating request, as well as an array of error messages for each failed contact.
- params (array of objects): A list of parameters to include in the callback request. Add each parameter in the form of a key-value pair. For a GET request, each parameter will be appended to the end of the URL in a query string. For a POST request, parameters will be included in the body of the request.
- headers (array of objects): A list of headers to include in the callback request. Add each header in the form of a key-value pair.
Contact Tags - Api Reference
client.contact_tags.all(contact_id)
client.contact_tags.create({
contact: contact_id,
tag: tag_id
})
BODY PARAMS
- contact* (integer): Contact's id
- tag* (integer): Tag's id
client.contact_tags.find(contact_tag_id)
client.contact_tags.delete(contact_tag_id)
Contact Automations - Api Reference
client.contact_automations.all(contact_id)
Contact Score Values - Api Reference
client.contact_score_values.all(contact_id)
Email Activities - Api Reference
client.email_activities.all
QUERY PARAMS (Optional)
- filters[subscriberid] (integer): Set this parameter to return only email activities belonging to a given subscriber.
- filters[dealId] (integer): Set this parameter to return only email activities belonging to a given deal.
Custom Fields - Api Reference
client.custom_fields.create({
type: "textarea",
title: "Field Title",
descript: "Field description",
perstag: "Personalized Tag",
defval: "Defaut Value",
visible: 1,
ordernum: 1
})
BODY PARAMS
- title* (string): Title of the field being created
- type* (string): Possible Values: dropdown, hidden, checkbox, date, text, datetime, textarea, NULL, listbox, radio
- descript (string): Description of field being created
- perstag (string): The perstag that represents the field being created
- defval (string): Default value of the field being created
- show_in_list (boolean): Show this field in the contact list view (Deprecated - no longer used)
- visible (boolean): Show or hide this field when using the Form Builder
- service (string): Possible Vales: nimble, contactually, mindbody, salesforce, highrise, google_spreadsheets, pipedrive, onepage, google_contacts, freshbooks, shopify, zendesk, etsy, NULL, bigcommerce, capsule, bigcommerce_oauth, sugarcrm, zohocrm, batchbook
- ordernum (integer): Order of appearance in ‘My Fields’ tab.
client.custom_fields.find(field_id)
client.custom_fields.update(field_id, {
title: 'Updated Field Title'
})
client.custom_fields.delete(field_id)
client.custom_fields.all
QUERY PARAMS (Optional)
- limit (integer): The number of fields returned per request.
client.custom_fields.link_to_list(field_id, list_id)
Custom Fields Options - Api Reference
client.custom_field_options.create([
{
field: custom_field_id,
label: option_1_title,
value: option_1_value
},
{
field: custom_field_id,
label: option_2_title,
value: option_2_value
}
])
BODY PARAMS
- field* (integer): ID of the custom field to add options to
- label (string): Name of the option
- value* (string): Value of the option
- orderid (integer): Order for displaying the custom field option
- isdefault: Whether or not this option is the default value
client.custom_field_options.find(field_option_id)
client.custom_field_options.delete(field_option_id)
Custom Fields Values - Api Reference
client.custom_field_values.create({
contact: contact_id,
field: field_id,
value: value
}, use_defaults: true)
BODY PARAMS
- contact* (string/integer): ID of the contact whose field value you're updating
- field* (string/integer): ID of the custom field whose value you're updating for the contact
- value* (string): Value for the field that you're updating. For multi-select options this needs to be in the format of ||option1||option2||
- use_defaults: If true, this will populate the missing required fields for this contact with default values
client.custom_field_values.find(field_value_id)
client.custom_field_values.update(
field_value_id,
{ value: value },
use_defaults: false
)
client.custom_field_values.delete(field_value_id)
client.custom_field_values.all
Users - Api Reference
client.users.create({
first_name: 'Phoebe',
last_name: 'Buffay',
username: 'raginaphalange',
password: 'smellycat',
email: 'ragina.phalange@smellycat.com'
})
BODY PARAMS
- username* (string): Username
- email (string): Email address
- first_name (string): First name
- last_name (string): Last name
- group (string/integer): Group ID
- password (string): Plain text password
client.users.find(user_id)
client.users.logged_in
client.users.find_by_email(email)
client.users.find_by_username(username)
client.users.update(user_id, {
password: 'newsmellycat',
group: group_id
})
Note: Group ID is mandatory in update.
client.users.delete(user_id)
client.users.all
Groups - Api Reference
client.groups.create({
title: 'Admin',
descript: 'This is a group for admin users (people that can manage content)'
})
BODY PARAMS
- title* (string): Title of the group to be created
- descript (string): Group description
- pg_message_add (boolean): Permission for adding messages
- unsubscribelink (boolean): Whether or not to force unsubscribe links
- optinconfirm (boolean): Whether or not to force optin confirm for this group
- pg_list_add (boolean): Permission for adding lists
- pg_list_edit (boolean): Permission for editing lists
- pg_list_delete (boolean): Permission for deleting lists
- pg_list_headers (boolean): Permission for managing custom email headers
- pg_list_emailaccount (boolean): Permission for managing Unsubscribe By Email
- pg_list_bounce (boolean): Permission for accessing list bounce settings
- pg_message_edit (boolean): Permission for editing messages
- pg_message_delete (boolean): Permission for deleting messages
- pg_message_send (boolean): Permission for sending messages
- pg_contact_add (boolean): Permission for adding contacts
- pg_contact_edit (boolean): Permission for editing contacts
- pg_contact_delete (boolean): Permission for deleting contacts
- pg_contact_merge (boolean): Permission for merging contacts
- pg_contact_import (boolean): Permission for importing contacts
- pg_contact_approve (boolean): Permission for approving contacts
- pg_contact_export (boolean): Permission for exporting contacts
- pg_contact_sync (boolean): Permission for syncing contacts
- pg_contact_filters (boolean): Permission for managing contact list segments
- pg_contact_actions (boolean): Permission for managing contact actions
- pg_contact_fields (boolean): Permission for managing contact custom fields
- pg_user_add (boolean): Permission for adding users
- pg_user_edit (boolean): Permission for editing users
- pg_user_delete (boolean): Permission for deleting users
- pg_group_add (boolean): Permission for adding groups
- pg_group_edit (boolean): Permission for editing groups
- pg_group_delete (boolean): Permission for deleting groups
- pg_template_add (boolean): Permission for adding templates
- pg_template_edit (boolean): Permission for editing templates
- pg_template_delete (boolean): Permission for deleting templates
- pg_personalization_add (boolean): Permission for adding personalization tags
- pg_personalization_edit (boolean): Permission for editing personalization tags
- pg_personalization_delete (boolean): Permission for deleting personalization tags
- pg_automation_manage (boolean): pgFormEdit (boolean): Permission for editing subscription forms
- pg_reports_campaign (boolean): Permission for viewing campaign reports
- pg_reports_list (boolean): Permission for viewing list reports
- pg_reports_user (boolean): Permission for viewing user reports
- pg_startup_reports (boolean): Campaign ID of last campaign report viewed to decide whether to show link on startup
- pg_reports_trend (boolean): Permission for viewing trend reports
- pg_startup_gettingstarted (boolean): Whether or not to show the "getting started" tutorial on overview page
- pg_deal (boolean): Permission for viewing deals
- pg_deal_delete (boolean): Permission for deleting deals
- pg_deal_reassign (boolean): Permission for reassigning deals
- pg_deal_group_add (boolean): Permission for adding deal groups
- pg_deal_group_edit (boolean): Permission for editing deal groups
- pg_deal_group_delete (boolean): Permission for deleting deals groups
- pg_saved_responses_manage (boolean): Permission for managing saved responses
- pg_tag_manage (boolean): Permission for managing tags
- req_approval (boolean): Whether or not this group requires all campaigns to be approved
- req_approval_1st (boolean): Whether or not this group requires first campaign to be approved
- req_approval_notify_string (string): Who to notify for approval related issues (email)
- socialdata (boolean): Whether or not to show social links in campaigns sent from this group
client.groups.find(group_id)
client.groups.update(group_id, {
title: 'Updated Group Title'
})
client.groups.delete(group_id)
client.groups.all
Templates - Api Reference
client.templates.find(template_id)
client.templates.delete(template_id)
client.templates.all
Task Types - Api Reference
client.task_types.create({
title: 'Call'
})
BODY PARAMS
- title* (string): Deal task type's title. The title should be unique among deal task types.
client.task_types.find(task_type_id)
client.task_types.update(task_type_id, {
title: 'New super cool title'
})
client.task_types.delete(task_type_id)
client.task_types.all
client.task_types.move_tasks(from_task_type_id, to_task_type_id)
Bug reports and pull requests are welcome on GitHub at https://github.com/anmol-yousaf/active_campaign_wrapper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
See the LICENSE file for more info.
Everyone interacting in the ActiveCampaignWrapper project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.