Documentation
How can we help?
Guides, tutorials and developer references for Groundhogg. Search for what you want to do, or browse by topic.
Start here
Getting Started
7
- Connect an AI Agent to GroundhoggConnect ChatGPT, Claude, Gemini or another AI agent to Groundhogg in a few clicks, and use it safely…
- Cron JobsGroundhogg relies on scheduled tasks (cron jobs) to send emails, process flows, and handle time-sensitive actions. By default,…
- Email BroadcastsNeed to send a one-off email to a segment of your contact list? That's what broadcasts are for!
- GDPR & CASL ComplianceGroundhogg gives you the tools to stay compliant with major privacy laws like the General Data Protection Regulation…
- Importing ContactsWhether you're switching from another CRM or just getting started, importing your existing contacts into Groundhogg is quick…
- Initial Setup GuideAfter installing Groundhogg, there are a few important configuration steps to complete before you can start using all…
- Installation GuideFirst-time customers can have our team install and setup Groundhogg for you!
Tutorials
4
- Lead DistributionThere are three common ways that you can distribute leads among a group of sales representatives using flows…
- Pruning your email listOver time, every email list accumulates contacts who no longer open, click, or engage with your emails. Continuing…
- RTL SupportGroundhogg emails support native RTL.
- Translating Groundhogg into your languageIf Groundhogg does not provide a translation for your language, or you want o modify one of the…
FAQ
4
- How to downgrade your licenseOur system makes downgrades difficult 🥲. To downgrade your license, please follow these steps.
- How to update your license keyIf you've purchased a new license key because you've upgraded or downgraded your account, and need to change…
- What is SMTP?SMTP (Simple Mail Transfer Protocol) is the technology responsible for delivering emails from your website to your contacts'…
- Where do I submit a support ticket?Need help from the Groundhogg team? Open a support ticket and we'll help you get it sorted as…
Using Groundhogg
Contacts
9
- Contact RecordThe Contact Record is the detailed view of a single contact, showing all of their information, activity, and…
- ContactsThe Contacts screen is where you search, filter, and manage every contact in your CRM. For details on…
- Custom FieldsCustom fields in Groundhogg allow you to store additional, structured information about your contacts beyond the default fields…
- Export ContactsTo export your contacts to a CSV file, navigated to Groundhogg >> Contacts and use the search filters…
- Importing ContactsWhether you're switching from another CRM or just getting started, importing your existing contacts into Groundhogg is quick…
- Importing Contacts with Their Opt-in StatusBy default, contacts imported for the first time get the opt-in status Unconfirmed. Depending on where you are…
- Merging ContactsIf you have multiple contact records for the same entity or person, you may want to merge them…
- Opt-in Status & MarketabilityGroundhogg uses the opt-in status plus other factors to determine the marketability of a contact. Marketability being whether…
- Search FiltersSearch filters are Groundhogg's primary tool for contact segmentation. You'll also find them everywhere in Groundhogg since we…
Email
9
- Editor Settings & DefaultsYou can customize the email editor to match your brand and workflow. Configure reusable fonts, default block settings,…
- Email BroadcastsNeed to send a one-off email to a segment of your contact list? That's what broadcasts are for!
- Global BlocksGlobal Blocks make it easy to reuse content across multiple emails. Create a block once, insert it anywhere,…
- Replies & MessagesMessages shows your email conversation with a contact on their record, like a text message thread: what you…
- Send Time OptimizationSend emails at the best time to encourage more opens and clicks!
- Sender ProfilesA sender profile is the combination of "From Name" and "From Email Address" that can be selected for…
- Transactional Vs Marketing EmailsUnderstanding the difference between transactional and marketing emails is essential for maintaining compliance and ensuring proper email deliverability.…
- UTM ParametersUTM parameters help you understand where your website traffic is coming from by providing detailed information about the…
- What is SMTP?SMTP (Simple Mail Transfer Protocol) is the technology responsible for delivering emails from your website to your contacts'…
Flows
6
- Flow Actions
- Flow Logic
- Flow Triggers
- How Flows WorkFlows are the primary automation feature in Groundhogg. They allow you to create automated customer journeys and experiences…
- Testing Flows with the SimulatorThe Flow Simulator lets you test and troubleshoot your flows before putting real contacts through them. By selecting…
- Using the Flow EditorYou will use the flow editor to create flows in Groundhogg.
Triggers
16
- Custom ActivityThe Custom Activity Trigger in Groundhogg allows developers and third-party integrations to initiate actions in a flow by…
- Flow Triggers
- Link ClickThe Link Click Trigger initiates actions in a flow when a contact clicks a designated link. This trigger…
- Logs InThe Logs In Trigger initiates actions within a Groundhogg flow when a user logs into your WordPress site.…
- Opt-in Status ChangedThe Opt-in Status Changed Trigger allows you to initiate actions in a flow whenever a contact's opt-in status…
- Opt-in Status ConfirmedThe Opt-in Status Confirmed Trigger initiates actions in a flow when a contact confirms their opt-in status, typically…
- Page VisitedThe Page Visited Trigger initiates a flow when a contact visits a specific webpage. This trigger is useful…
- Plugin API TriggerThe Plugin API Trigger in Groundhogg provides a way for developers to create custom triggers within a flow,…
- Post PublishedThe Post Published Trigger in Groundhogg initiates actions when a post or custom post type is published on…
- Role ChangedThe "Role Changed" Trigger in Groundhogg allows you to initiate actions in a flow when a contact's user…
- Tag AppliedThe Tag Applied Trigger in Groundhogg enables you to start a flow when specific tags are applied to…
- Tag RemovedThe Tag Removed Trigger in Groundhogg initiates specific actions within a flow when one or more tags are…
- Task CompletedThe Task Completed Trigger in Groundhogg allows you to initiate actions within a flow when a contact completes…
- Trigger SettingsTrigger Settings are a core component of every trigger in Groundhogg CRM's flow builder. These settings provide essential…
- User CreatedThe User Created Trigger in Groundhogg initiates actions when a new user is created in WordPress, either through…
- Webhook ListenerThe Webhook Listener Trigger in Groundhogg allows you to initiate flow actions based on data received from external…
Actions
15
- Add NoteThe Add Note action lets you automatically attach a note to a contact’s record while they move through…
- Admin NotificationThe Admin Notification action in Groundhogg sends an email to specified administrators or users when a contact reaches…
- Advanced TimerThe Advanced Timer action in Groundhogg allows you to schedule flow steps using flexible, human-readable time expressions, such…
- Apply TagThe "Apply Tag" action in Groundhogg is a flow step that assigns a specific tag(s) to contacts who…
- Assign OwnerThe Assign Owner action in Groundhogg enables you to assign or reassign a contact to one or more…
- Create TaskThe Create Task action in Groundhogg allows you to automatically generate tasks for contacts within a flow. This…
- Create UserThe Create User action in Groundhogg enables the automatic creation of a WordPress user account for a contact…
- Date TimerThe Date Timer action in Groundhogg allows you to schedule a specific action to occur at a precise…
- Delay TimerThe Delay Timer action in Groundhogg allows you to pause the progression of a flow for a specified…
- Edit Custom FieldsThe Edit Custom Fields action in Groundhogg allows you to update metadata associated with a contact or user…
- Field TimerThe Field Timer action in Groundhogg allows you to pause a flow until a specific date stored in…
- Plugin API ActionThe Plugin API Action in Groundhogg enables developers to create custom actions within a flow by integrating bespoke…
- Remove TagThe Remove Tag action in Groundhogg allows you to automatically remove one or more tags from a contact…
- Send EmailThe Send Email action in Groundhogg allows you to automatically send an email to a contact as part…
- WebhookThe Webhook action in Groundhogg enables seamless communication with external software or other Groundhogg instances on different websites.…
Logic
9
- Flow Logic
- LoopThe Loop logic in Groundhogg allows you to repeatedly execute a set of actions for contacts who meet…
- Multi BranchMulti Branch, also known as multi-path branching or prioritized conditional routing, extends beyond the binary Yes/No logic to…
- Random DistributionRandom Distribution Settings in Groundhogg CRM provide a probabilistic method for directing contacts through multiple branches in a…
- SkipThe Skip logic in Groundhogg allows you to bypass specific steps in a flow based on predefined conditions.…
- Smart Date SequenceThe Smart Date Sequence is a Logic step in your Flow that dynamically directs contacts to the most…
- Split (A/B) TestSplit (A/B) Testing in Groundhogg CRM is a dynamic experimentation tool designed to optimize flow performance by comparing…
- StopThe Stop logic is a critical component in your automation flow that allows you to halt a contact's…
- Yes/NoYes/No logic, also known as conditional branching or binary decision-making, is a core feature in Groundhogg CRM's flow…
Administration
5
- CampaignsCampaigns are an organization tool for your marketing assets. Think of them like categories for flows, emails, and…
- GDPR & CASL ComplianceGroundhogg gives you the tools to stay compliant with major privacy laws like the General Data Protection Regulation…
- Interface ThemesChoose Light, Paper, Slate or Midnight for the Groundhogg admin. Themes are saved per user and only change…
- Mobile AppInstall Groundhogg on your phone to look up contacts, call, text or email them, work through tasks, add…
- User Roles & CapabilitiesGroundhogg separates most of its functionality into user roles and various capabilities. Below we describe what roles are…
Personalization
2
Lead Generation
2
Search & Segmentation
4
- Custom Contact Search FiltersWant to add your own custom search filters to Groundhogg? It's easy! You just need two files.
- Opt-in Status & MarketabilityGroundhogg uses the opt-in status plus other factors to determine the marketability of a contact. Marketability being whether…
- Pruning your email listOver time, every email list accumulates contacts who no longer open, click, or engage with your emails. Continuing…
- Search FiltersSearch filters are Groundhogg's primary tool for contact segmentation. You'll also find them everywhere in Groundhogg since we…
Troubleshooting
7
- Caching CompatibilityCaching is great for speeding up your site, but it can be a problem when you have dynamic…
- Cron JobsGroundhogg relies on scheduled tasks (cron jobs) to send emails, process flows, and handle time-sensitive actions. By default,…
- How to Enable Safe ModeSafe Mode in Groundhogg is a troubleshooting tool designed to help users identify conflicts between Groundhogg and other…
- Recommended Test ProceduresTo test flows the best method is to use the Flow Simulator. It provides as easy and interactive…
- Tracking links/superlinks not workingIf you've noticed that tracking links, superlinks, or confirmation links are not working, follow this guide to understand…
- Why can’t I activate my WaaS license on subsites?How the WaaS license covers every subsite on a multisite network, including subsites with custom or mapped domains.
- Why is my license not being recognized?Why your site might say your Groundhogg license is invalid or expired when it's active in your account,…
Known Issues & Workarounds
2
Add-ons
Sales Add-ons
1
Marketing Add-ons
2
Integrations
Ecommerce
3
- Easy Digital DownloadsEasy Digital Downloads (EDD) is a top-tier eCommerce solution for companies exclusively selling digital products (Audio Files, PDFs, WordPress…
- GiveWPGiveWP is one of the most popular donation plugins for WordPress, with over 100,000 active users. GiveWP offers a…
- WooCommerceWooCommerce is one of many eCommerce solutions that are available for WordPress. Groundhogg has an integration with WooCommerce.
Forms
3
- Cloudflare TurnstileTo use Cloudflare Turnstile to protect your Groundhogg forms you'll first need to create a turnstile secret key…
- Elementor Forms IntegrationIf you use Elementor forms and want to send that information to Groundhogg you need this extension. Easily…
- Google reCAPTCHATo use reCAPTCHA to protect your forms, first create a site key and secret key.
Learning Management
4
- LearnDashLearnDash is a top-tier LMS plugin that turns your WordPress website into a learning portal. Groundhogg provides direct integration…
- LifterLMSLifterLMS is a top-tier LMS plugin that turns your WordPress website into a learning portal. Groundhogg provides direct…
- MemberPressMemberPress is one of the most popular membership plugins for WordPress, allowing you to create and manage memberships,…
- Tutor LMSTutor LMS is a feature-rich, easy-to-use learning management plugin for WordPress. Groundhogg provides direct integration with Tutor LMS,…
SMS Services
3
- seven (formerly SMS77)Send your Groundhogg SMS through seven.io (formerly SMS77).
- Text Messaging (SMS)Send text messages from Groundhogg: SMS templates, the Send SMS and SMS Admin Notification flow actions, and the…
- Twilio & WhatsAppSend SMS and WhatsApp messages through Twilio, receive replies, and build text-to-subscribe opt-in flows.
SMTP Services
3
- Elastic EmailGroundhogg integrates with Elastic Email to provide fast, reliable, and cost-effective delivery of transactional and marketing emails. This…
- PostmarkGroundhogg integrates with Postmark to provide ultra-fast, reliable delivery of transactional and marketing emails. This guide walks you…
- SendGridGroundhogg integrates with SendGrid to deliver fast and reliable email at scale. This guide walks you through installing…
Developer
Developer Guides
8
- Building Custom Flow StepsRegister a custom flow step type, draw its settings with Funnel.registerStepType(), and expose it to AI agents through…
- Custom Contact Search FiltersWant to add your own custom search filters to Groundhogg? It's easy! You just need two files.
- Custom Flow Triggers and ActionsHave special site functionality that you want to use within your flows? With the Advanced Features add-on you…
- Custom post data within the query loop blockLooking to add even more details about your posts in the query loop block? There are a couple…
- Custom queries for the posts and query loop blocksIt's super easy to modify the query for the posts block and the query loop block in the…
- Translating Groundhogg into your languageIf Groundhogg does not provide a translation for your language, or you want o modify one of the…
- Working with the Abilities API (MCP)Groundhogg supports the WordPress Abilities API, a standard way of registering discrete, well-defined actions and queries that other…
- Working with the Activity APIThe Activity API is a flexible way of tracking historical contact interactions with your site. The Activity API…
Code Samples
2
Rest API
2
Action Hooks
30
- groundhogg/activatedFires just after a Groundhogg plugin or extension has been activated and its installer has run. Use this…
- groundhogg/activatingFires just before a Groundhogg plugin or extension is activated. Use this to run pre-activation checks in your…
- groundhogg/admin/contact/saveFires after a contact record has been saved from the admin edit screen. All standard fields and meta…
- groundhogg/admin/contacts/register_info_cardsFires when Groundhogg registers the info cards shown in the right sidebar of the contact record. Hook here…
- groundhogg/admin/funnel/updatedFires after a funnel has been saved from the funnel editor. Use this to sync changes to an…
- groundhogg/admin/initFires when the Groundhogg admin menu is initialised. This is the correct place to register new admin pages…
- groundhogg/admin/register_settings/beforeFires before Groundhogg registers its settings fields. Use this to add custom tabs, sections, or fields to the…
- groundhogg/contact_created_from_userFires when Groundhogg automatically creates a contact record from a WordPress user registration or login. Use this to…
- groundhogg/contact/agreed_to_termsFires when a contact agrees to the site's terms and conditions. Use this to record consent in a…
- groundhogg/contact/createdFires when a brand-new contact record is created via Contact::create(). At this point the contact exists in the database,…
- groundhogg/contact/mergedFires after two contact records have been merged. The primary contact has absorbed all data from the secondary,…
- groundhogg/contact/owner_changedFires when the assigned owner of a contact is changed.
- groundhogg/contact/record/nav/insideFires inside the contact record tab navigation. Use this to add custom tabs to the contact edit screen.
- groundhogg/contact/tag_appliedFires each time a single tag is applied to a contact. When multiple tags are applied at once…
- groundhogg/contact/tags_removedFires once after a batch of tags has been removed from a contact. The complement to groundhogg/contact/tags_applied.
- groundhogg/create_contact_from_userFires after a contact is created from an existing WordPress user. Use this to copy custom user meta…
- groundhogg/deactivatedFires just after a Groundhogg plugin or extension has been deactivated. Use this to clean up options or…
- groundhogg/email_logger/after_create_logFires after an email log entry has been written to the database. Use this to forward log data…
- groundhogg/email/after_sendFires after an Email object has finished its send attempt, whether it succeeded or failed.
- groundhogg/email/send_failedFires when an email send attempt fails.
- groundhogg/form/v2/submitFires after a v2 Groundhogg form is successfully submitted, the contact record has been created or updated, and…
- groundhogg/loadedFires after Groundhogg has fully loaded and instantiated all of its components — the earliest safe point to…
- groundhogg/preferences/download_profileFires when a contact requests a download of their personal data from the preferences page. Use this to…
- groundhogg/preferences/erase_profileFires when a contact requests erasure of their personal data from the preferences page. Use this to delete…
- groundhogg/preferences/manage/preferences_updatedFires after a contact updates their marketing preference from the manage-preferences page. Use this to sync the change…
- groundhogg/preferences/profile_formFires inside the profile form on the Groundhogg preferences page, after the built-in fields. Use this to add…
- groundhogg/resetFires when the Groundhogg reset tool is triggered from the admin tools page. Use this to also reset…
- groundhogg/scripts/after_register_admin_scriptsFires after Groundhogg registers its admin JavaScript files. Use this to register custom admin scripts that depend on…
- groundhogg/steps/benchmarks/apiFires when do_api_benchmark() is called, allowing extensions to hook into any API benchmark trigger fired anywhere in the system.
- groundhogg/templates/email/headFires inside the <head> of every Groundhogg email template. Use this to inject custom <style> blocks that should appear in all outgoing…
Filter Hooks
29
- groundhogg/admin/contact/record/tabsFilters the tabs displayed on the contact record edit screen. Use this to add custom tabs to the…
- groundhogg/admin/settings/tabsFilters the tabs displayed on the Groundhogg settings page. Use this to add a custom settings tab for…
- groundhogg/admin/tools/tabsFilters the tabs on the Groundhogg tools page. Use this to add a custom tab for extension-specific tools…
- groundhogg/confirmation_urlFilters the email confirmation URL generated for a contact. Use this to redirect confirmations through a custom landing…
- groundhogg/contact/is_deliverableFilters whether a contact's email address is considered deliverable. Return false to treat a contact as undeliverable — for example,…
- groundhogg/contact/is_marketableFilters whether a contact is considered marketable. Called inside Contact::is_marketable() before any email is sent. Return false to suppress sends to a…
- groundhogg/contact/profile_pictureFilters the profile picture URL for a contact. By default this returns a Gravatar URL. Use this to…
- groundhogg/email_template/footer_textFilters the custom footer text block that appears in the Groundhogg email footer. Use this to add a…
- groundhogg/email_template/unsubscribe_textFilters the anchor text of the unsubscribe link in the email footer.
- groundhogg/email/subjectFilters the subject line of an email just before it is sent, after merge tags have been processed.
- groundhogg/email/the_contentFilters the fully processed HTML content of an email after all blocks have been rendered and merge tags…
- groundhogg/email/toFilters the To email address just before a message is sent. Use this to redirect emails — for example, to…
- groundhogg/form/submission_handler/contact_argsFilters the contact creation arguments assembled from a form submission, just before the contact record is created or…
- groundhogg/form/submission_handler/is_spamFilters whether a form submission should be treated as spam. Return true to reject the submission from your own spam…
- groundhogg/form/v2/success_urlFilters the redirect URL a contact is sent to after a successful v2 form submission.
- groundhogg/get_default_from_emailFilters the default From email address used when sending Groundhogg emails.
- groundhogg/get_default_from_nameFilters the default From name used when sending Groundhogg emails.
- groundhogg/mappable_fieldsFilters the list of contact fields available for mapping in the form builder and import tools. Use this…
- groundhogg/owner_rolesFilters the WordPress roles whose users are eligible to be contact owners. Use this to add a custom…
- groundhogg/ownersFilters the array of WordPress users available as contact owners in dropdowns and assignment tools.
- groundhogg/post_merge_tagsFilters the list of available merge tags passed to the email block editor after the built-in tags have…
- groundhogg/roles/caps/contactsFilters the capabilities array assigned to the contacts permission group. Use this to add or remove granular contact…
- groundhogg/sanitize_object_metaFilters a meta value before it is saved to the database for any Groundhogg object. Use this to…
- groundhogg/should_convert_user_to_contact_when_user_registeredFilters whether a newly registered WordPress user should automatically be converted to a Groundhogg contact. Return false to prevent automatic…
- groundhogg/step/can_completeFilters whether a benchmark step can be completed for a contact. Return true to allow a contact to enter a…
- groundhogg/step/enqueue/eventFilters the event arguments array just before it is added to the event queue for a funnel step.…
- groundhogg/steps/run/do_stepFilters whether a funnel step should run for a contact. Return false to skip the step for a specific contact…
- groundhogg/tracking/target_urlFilters the destination URL a contact is redirected to when they click a tracked link in an email.…
- groundhogg/unsubscribe_urlFilters the unsubscribe URL generated for a contact. Use this to redirect unsubscribes through a custom preferences page.
Functions
26
- add_action_use_onceRegisters an action callback that automatically removes itself the first time it fires, so it only runs once…
- add_event_argsAttaches additional arguments to the currently executing event during queue processing. These args are stored on the event…
- add_filter_use_onceRegisters a filter callback that automatically removes itself after being called once. The filter only modifies the value…
- after_form_submit_handlerThe after_form_submit_handler() function handles many post-form submission tasks, such as...
- confirmation_urlGenerates a personalised email confirmation URL for a contact. When clicked, the contact's opt-in status is updated to…
- create_contact_from_userCreates a Groundhogg contact record from an existing WordPress user. If the user already has a corresponding contact,…
- create_user_from_contactCreates a WordPress user account from a Groundhogg contact. The contact's email is used as the username and…
- do_api_benchmarkTriggers any funnel API Benchmark step that is listening for the given call name. This is the primary…
- do_replacementsProcesses Groundhogg merge tags (e.g. {first_name}, {email}) in a string and returns the result with all recognised tags replaced by…
- do_replacements_plain_textIdentical to do_replacements() but processes merge tags in plain-text context so HTML entities are not escaped. Use this for plain-text…
- enqueue_eventAdds an event to the Groundhogg event queue for processing on the next cron run. This is the…
- generate_contact_with_mapCreates or updates a contact from an associative array of field values and an optional field map. The…
- get_contactdataThe primary helper for retrieving a contact record. Pass a contact ID, email address, or WordPress user ID…
- get_current_contactAlias for get_contactdata() called with no arguments. Returns the current contact detected from the active event queue or tracking cookie.…
- get_dbReturns a Groundhogg database table instance by its key name. Each table provides query(), add(), update(), delete(), and count() methods for direct database access…
- get_event_argRetrieves a named argument from the currently executing event during queue processing. Use this to read data attached…
- gh_mailGroundhogg's low-level mail-sending function. Works like WordPress's wp_mail() but routes the message through the Groundhogg email service configured in settings…
- is_a_contactReturns true if the given value is an instance of \Groundhogg\Contact and the contact exists in the database. Use this as a…
- managed_page_urlReturns the URL to a path within Groundhogg's managed page — the special page that handles the preferences…
- permissions_key_urlAppends a secure, time-limited permissions key (?pk=…) to a URL for a specific contact. The key allows Groundhogg…
- send_email_notificationQueues a Groundhogg email template to be sent to a contact. The email is added to the event…
- track_activityRecords a custom activity event for a contact. Activities appear in the contact's activity log, can trigger activity-based…
- track_page_visitRecords a page visit for a contact. Groundhogg calls this automatically when a tracked contact follows a link…
- unsubscribe_urlGenerates a personalised unsubscribe URL for a contact. Depending on whether one-click unsubscribe is enabled in Groundhogg settings,…
- update_contact_with_mapUpdates an existing contact from an associative array of field values and a field map. This is a…
- validate_tagsNormalises a mixed tag input into a clean array of valid integer tag IDs. Accepts a single value…
Classes
13
- \Groundhogg\Broadcastextends Base_Object_With_Meta implements Event_Process
- \Groundhogg\Campaignextends Base_Object
- \Groundhogg\Classes\Noteextends Base_Object
- \Groundhogg\Classes\Taskextends Note
- \Groundhogg\Contactextends Base_Object_With_Meta
- \Groundhogg\Emailextends Base_Object_With_Meta
- \Groundhogg\Eventextends Base_Object
- \Groundhogg\Funnelextends Base_Object_With_Meta
- \Groundhogg\Stepextends Base_Object_With_Meta implements Event_Process
- \Groundhogg\Submissionextends Base_Object_With_Meta
- \Groundhogg\Tagextends Base_Object
- abstract \Groundhogg\Base_Objectimplements Serializable, ArrayAccess, JsonSerializable
- abstract \Groundhogg\Base_Object_With_Metaextends Base_Object
Nothing matches that. Try another word, or ask us.
Can’t find it?
Ask us. Customers get a reply from a real person, and your question often turns into a new article.
Want it done fast?
Skip the reading. Tell us what you want built and we will build it for you inside Groundhogg, for a flat $60 per task.