iContact Integration

iContact Integration connects any Drupal 10 or 11 site to the iContact email marketing platform via the iContact REST API v2.2. Drop the included iContact Subscribe field onto your user account form, map your Drupal user fields to iContact contact fields, define per-role subscription rules, and contacts are created, deduplicated, and subscribed automatically — all without blocking page requests, thanks to asynchronous cron-based queue processing. Whether you are running a traditional Drupal site, a decoupled React or Vue application, or a Webform-driven sign-up flow, iContact Integration gives you a complete, production-ready email-marketing bridge — with a custom JSON REST API, optional Drupal REST resources, three developer hooks, credential security via environment variables or settings.php, and a built-in admin dashboard showing your live mailing lists and queue status.

Features

Contact Management & Subscriptions

• Contact deduplication — Before creating a new contact, the module looks up the email address in iContact and reuses the existing record, preventing duplicate entries.
• Full CRUD API coverage — Contacts, mailing lists, subscriptions, messages, campaigns, segments, sends, statistics, and bulk uploads are all accessible through the injectable service.
• Subscribe / unsubscribe — Contacts can be subscribed or unsubscribed from individual lists or from all lists in a single call.
• Subscription status control — Set the iContact status to normal, pending, or unsubscribed per subscription.
• Batch contact import — addContacts() submits multiple contacts in a single API call for efficient bulk onboarding.

User Subscription Rules

• Per-role subscription rules — Each Drupal user role is independently configured with its own target iContact mailing list, subscription trigger, and unsubscription policy.
• Two subscription triggers — Subscribe when a new account is created ( hook_user_insert), or subscribe only when the user explicitly checks the iContact Subscribe opt-in field.
• Unsubscription on account delete — A per-role toggle automatically unsubscribes deleted users from the corresponding list.
• Role processing order — A configurable weight controls the order in which roles are processed when a user holds multiple active roles. All active roles are processed independently; the weight does not suppress lower-priority roles.
• Queue cancellation — Unchecking the Subscribe field on a profile edit instantly cancels any pending queue item and queues an unsubscription, preventing accidental double subscriptions.
• Change detection via $user->original
  — Saving a profile without touching the checkbox creates no queue items and makes no API calls.

iContact Subscribe Field Type

• Custom field type — The icontact_subscribe field type attaches to the user entity via Drupal's standard Manage Fields UI and renders as an opt-in checkbox on registration and profile edit forms.
• Configurable label — Set the label to anything ("Subscribe to our newsletter", "Join the mailing list", etc.) per field instance.
• Tight integration with subscription rules — When the checkbox trigger is selected in User Subscription Configuration, this field drives the subscribe / unsubscribe lifecycle end-to-end.

Asynchronous Queue Processing

• Non-blocking registrations — With the queue option enabled (default), subscription API calls are dispatched to the icontact_subscription_queue Drupal queue and processed during cron, so user registration is never slowed by an outbound API call.
• Automatic retry — Failed queue items are retried on subsequent cron runs; the worker is allocated 30 seconds per run.
• Manual processing — The queue can be drained at any time with drush queue:run icontact_subscription_queue.
• Cancellation safety net — A Drupal State flag prevents a claimed-but-not-yet-processed subscribe item from executing after the user has unchecked the field.

Field Mapping

• Field Mapping UI — Map any string, string_long, or email Drupal user field to an iContact contact field (firstName, lastName, phone, city, state, and more).
• Custom fields support — Query all iContact custom contact fields via the API and include them in mappings.
• Email auto-mapping — The user's email address is always mapped automatically; no manual configuration required.
• Dynamic field discovery — Available iContact contact field names are fetched live from the API and cached for 10 minutes, so new custom fields are picked up without any code change.

Admin Dashboard & UI

• Dashboard — View all iContact mailing lists and current queue depth from within Drupal at /admin/icontact-integration/dashboard.
• Connection test — The API Keys form includes a Save & Test Connection button that verifies credentials without leaving the admin UI.
• Sandbox mode — A single checkbox switches all API calls to app.sandbox.icontact.com for safe testing.
• Debug logging — Optional full request/response watchdog logging for every API call, viewable at Reports → Recent log messages.
• Cache management — A one-click button in Advanced Settings invalidates the cached account ID, client folder ID, lists, and field names immediately.
• Requirements check — Drupal's Status Report displays a warning when API credentials are missing or incomplete.
• Built-in Help & About pages — Inline documentation and module information are available directly from the admin menu.

REST API & JSON Endpoints

• Custom JSON API (no extra modules required) — Nine ready-to-use endpoints at /api/icontact/* always return JSON and are controlled by the use icontact rest api Drupal permission.
• Drupal REST resources (optional) — Three @RestResource plugins ( icontact_subscribe, icontact_lists, icontact_contact) activate automatically when the core REST module is enabled, supporting all Drupal authentication methods and standard content negotiation.
• Headless / decoupled ready — CORS configuration, CSRF token flow, HTTP Basic Auth, and code examples for Angular, React, and Vue are all documented.
• Async subscribe endpoint — Pass "async": true in the POST body to dispatch the subscription to the cron queue rather than executing it inline.
• Health check endpoint — GET /api/icontact/ping provides a lightweight connectivity check for monitoring and load balancers.

Webform Integration (submodule)

• 
  icontact_integration_webform submodule — Adds an iContact Subscribe Webform handler that subscribes form submitters to a mailing list on submission.
• Opt-in checkbox support — Map a webform checkbox element as the opt-in gate; the subscription only fires when checked.
• Per-handler field mapping — Map any webform element to iContact contact fields (firstName, lastName, phone, city, state, etc.) directly in the handler configuration.
• Queue support — A per-handler toggle dispatches subscriptions to the cron queue to keep form submission responses fast.
• Subscription status — Choose normal (active) or pending (requires confirmation email) per handler.

Developer Experience

• Three hooks — hook_icontact_integration_user_data_alter, hook_icontact_integration_user_data, and hook_icontact_integration_contact_data_alter give full control over contact payloads before they reach the API.
• Injectable service — IcontactApiService is registered as icontact_integration.api in the service container and can be constructor-injected into any Drupal class.
• Raw API access — makeCall() is public and covers any iContact endpoint not wrapped by a helper method.
• Introspection helpers — getErrors(), getWarnings(), getTotal(), getLastRequest(), and getLastResponse() expose the full state of the last API call for debugging and logging.
• Credential security — Credentials are resolved from environment variables first, then settings.php config overrides, then the database — keeping secrets out of version control. The admin UI automatically disables overridden fields and shows an informational notice.
• Backward-compatible shim — The legacy iContactApi::getInstance() static accessor still works via a compatibility shim in 2.x, so existing custom code does not break during upgrades.
• Full config schema — All four config objects are fully schema-typed for Drupal config management compliance.
• PHP 8.1+ typed properties and declare(strict_types=1) throughout.
• PSR-4 autoloading under the clean Drupal\icontact_integration namespace.

Post-Installation

After enabling the module, follow these steps to get subscriptions flowing to iContact:

1. Get your iContact API credentials.
   
   Log in to your iContact account at app.icontact.com and go to Settings → API. Create or open an application to obtain your App ID, API Username (your account email), and App Password (the application-specific password, not your account password).
2. Enter credentials in Drupal.
   
   Go to Configuration → iContact Integration → API Keys & Credentials ( /admin/icontact-integration/api-keys). Fill in the App ID, API Username, and App Password. Check Sandbox if you are testing. Click Save & Test Connection to verify the credentials are accepted by the iContact API before proceeding.
3. Configure field mappings.
   
   Go to Configuration → iContact Integration → Field Mappings ( /admin/icontact-integration/field-mappings). For each iContact contact field (firstName, lastName, phone, etc.), select the matching Drupal user field from the dropdown. Only string, string_long, and email field types are listed. The email address is always mapped automatically.
4. Configure user subscription rules.
   
   Go to Configuration → iContact Integration → User Subscription Configuration ( /admin/icontact-integration/users). For each Drupal role you want to sync:
   • Enable the checkbox for the role.
   • Choose the subscription trigger: on account creation or via the iContact Subscribe checkbox field.
   • Select the target iContact mailing list.
   • Optionally enable Unsubscribe when account is deleted.
   • Set a processing weight if multiple roles need a specific order.
5. (Optional) Add the Subscribe checkbox field to the user form.
   
   Go to Configuration → People → Account settings → Manage fields ( /admin/config/people/accounts/fields). Add a new field of type iContact Subscribe. Set its label (e.g. "Subscribe to our newsletter"). The checkbox will appear on the registration form and profile edit form, and will drive subscriptions for any role configured with the checkbox trigger.
6. Review advanced settings.
   
   Go to Configuration → iContact Integration → Advanced Settings ( /admin/icontact-integration/advanced). Key options include:
   • Use queue (recommended) — processes subscriptions via cron to avoid request timeouts.
   • Debug logging — logs all API requests and responses to watchdog.
   • Clear data on uninstall — removes all configuration when the module is uninstalled.
7. Set permissions.
   
   Go to People → Permissions and configure:
   • access icontact integration configuration — full admin access; restrict to trusted roles.
   • access icontact dashboard — for editors or site managers who need to view mailing lists and queue status.
   • use icontact rest api — for roles that call the JSON REST endpoints; grant to the anonymous role to allow public newsletter sign-up forms from decoupled frontends.
8. View your dashboard.
   
   Your iContact mailing lists and live queue depth are available at Configuration → iContact Integration → Dashboard ( /admin/icontact-integration/dashboard). The Help and About tabs in the same menu section provide inline documentation and module version information.

For headless or decoupled frontends, grant the use icontact rest api permission to the appropriate role and use the POST /api/icontact/subscribe endpoint. For CSRF-protected calls from a logged-in session, obtain a token first with GET /session/token. Code examples for Angular, React, and Vue are provided in the README.md file included in the module.

Additional Requirements

• Drupal 10.x or 11.x
• PHP 8.1 or higher
• An active
  iContact
  account with API access enabled
• Drupal core modules: User, Field (both included in Drupal core)
• GuzzleHttp — bundled with Drupal core; no separate installation required

No third-party PHP libraries, JavaScript frameworks, or external services beyond iContact itself are required. The module is entirely self-contained.

Recommended Modules

• Webform — Required for the optional icontact_integration_webform submodule. Enables a dedicated iContact Subscribe handler that subscribes form submitters to any mailing list with full field mapping and opt-in checkbox support.
• JSON:API — Recommended for headless Drupal integrations. Use alongside the iContact Integration REST API to build fully decoupled React, Vue, or Angular frontends that handle both content and newsletter subscription from a single Drupal backend.
• Simple OAuth — Useful when your decoupled frontend authenticates users via OAuth 2.0 and needs to post subscription requests as an authenticated session.
• A Redis or Memcache cache backend — For high-traffic sites, swapping the default database cache backend to Redis or Memcache improves the response time of cached API data (account ID, client folder ID, mailing lists, and contact field names) significantly.

Similar Projects

• Mailchimp — The most widely used Drupal–email-marketing bridge, connecting to Mailchimp rather than iContact. Both modules provide role-based list subscriptions and a subscribe field. iContact Integration differs by targeting the iContact platform, offering a custom framework-agnostic JSON REST API (no REST module required), environment-variable credential management, and a backward-compatible 1.x shim.
• Simplenews — Manages newsletter subscriptions and sending entirely within Drupal using Drupal's own mail system. iContact Integration delegates all list management, sending infrastructure, deliverability, and analytics to the iContact platform, which is better suited for sites that rely on iContact's editor, templates, and reporting tools.
• Mautic — Bridges Drupal with the open-source Mautic marketing automation platform. iContact Integration targets the commercial iContact SaaS instead, and includes a built-in JSON REST API and Webform handler that Mautic's bridge does not provide out of the box.

Supporting This Module

If iContact Integration saves you time on your project, the best way to support continued development is to:

• Report bugs and suggest features in the project issue queue.
• Contribute patches, test coverage, or documentation improvements.
• Post a review on the project page — community ratings help others discover the module.
• Help test release candidates against Drupal 10 and 11 minor updates.

When reporting an issue, please include your Drupal core version, PHP version, iContact API version, the steps to reproduce, and any relevant log output from Reports → Recent log messages filtered by the icontact_integration channel. If the issue involves API calls, enable Debug logging in Advanced Settings first and include the full request/response from the log.

Community Documentation

• Full installation, configuration, field mapping, queue, hook, REST API, security, and Webform integration documentation is available in the README.md file included in the module.
• Developer hook documentation with annotated code examples is in the icontact_integration.api.php file inside the module.
• Video walkthroughs, step-by-step tutorials, and example integrations for React, Vue, Angular, and headless Drupal are welcome contributions — please link them in the issue queue and they will be added here.

Use Cases

iContact Integration is well suited for:

• Community and news sites — automatically subscribe registered users to role-based newsletters the moment they create an account.
• Membership and association sites — map each membership role to a dedicated iContact list and keep subscriber records in sync as roles change.
• Corporate intranets and knowledge bases — use field mapping to push employee profile data (department, location, job title) to iContact custom fields for targeted internal campaigns.
• Learning management systems — subscribe learners to course-specific lists when they enrol, and unsubscribe them automatically when their account is removed.
• Event and conference sites — use the Webform handler to capture registrant email addresses and field data into iContact lists directly from the event sign-up form.
• Decoupled / headless Drupal applications — consume the JSON REST API from any JavaScript frontend and let Drupal handle iContact authentication, queuing, deduplication, and field mapping in the background.
• E-commerce sites — combine the REST API with order-complete hooks to subscribe customers to post-purchase follow-up lists, with first name, last name, and other profile fields pre-populated.