Syncing EspoCRM reports to target lists

How to sync EspoCRM reports to target lists for campaigns

Report-based syncing keeps a campaign audience current by re-running a saved EspoCRM report and feeding its results into a target list, so the list reflects the records that match today rather than the records that matched when someone last rebuilt it by hand. A marketing or sales operations lead needs this when audiences drift between campaigns, when several people maintain overlapping lists, or when suppression rules such as opt-outs and existing-customer exclusions have to be applied every time a send is prepared. The reports themselves come from the Advanced Pack, an official add-on that is included in all EspoCRM Cloud plans and that also provides the Workflows and BPM engine. The exact sync mechanism, including whether it runs from a workflow, a scheduled job or a manual action, depends on the installed version and extensions, so confirm it against the release you plan to run before designing around it.

EspoCRM is licensed under AGPL-3.0, and the open-source edition can be downloaded and self-hosted for free, so the cost of the platform itself is not the question here. What you pay for is the Advanced Pack licensing path, the infrastructure that runs background jobs, and the configuration work. Ask the implementation partner and your own team to agree in writing which Advanced Pack features the design relies on, and whether the chosen route is supported on your self-hosted version. Confirm also how the sync treats records that were removed from the report, since a list that only grows will quietly keep contacts who should no longer receive a campaign.

Which sync approach fits which campaign pattern

This table compares four ways to keep a campaign target list in step with a report: a manual run, a scheduled Advanced Pack workflow or BPM process, Formula Script flags, and an external job calling the REST API. Read each row against your campaign cadence, the number of people who can maintain it, and how strictly you must show who was added, removed and why. Confirm the exact list-update action available in your installed version before you commit to a design.

Approach	Best fit and maintenance owner	Refresh frequency and removals	Audit trail
Manual report run and list update	Infrequent one-off campaigns; a marketing operations user runs the report and updates the list by hand	Refreshes only when someone acts, so removals and opt-outs can lag behind the send date	Limited to user activity history and whatever notes the operator records
Scheduled Advanced Pack workflow or BPM process	Recurring campaigns with a stable rule; an administrator owns the workflow and reviews it after upgrades	Runs on a schedule and can add and remove members, provided the list-update action in your version supports removal	Workflow and process logs show runs and actions, so test the log detail in your version
Formula Script before-save flag	Audiences defined by a field condition on the record itself, such as consent status; an administrator maintains the script	Updates when a record is saved, so records that change without a save are not reflected until the next save	Flag changes are tied to record modification history, but the flag alone does not show when the audience changed
External job calling the REST API with an API user	Large or cross-system audiences; a developer or integration team owns the code, credentials and schedule	Refreshes on the job schedule and can apply full replacements or incremental changes, depending on how it is written	Depends on logging in the job and API user activity, so the job must store its own run records

Setup sequence for a report-driven target list

This sequence turns a campaign audience defined by an EspoCRM report into a target list that stays current, excludes suppressed contacts and can be checked before any mail goes out. Each step ends with a check that confirms the list matches the intended audience.

Define the audience and its owner
Marketing and the campaign owner write down who the audience is, which record type it covers (contacts, leads or accounts), which fields qualify a record, and who approves changes to the criteria. Name one owner for the audience definition and one for the exclusion rules, since these are the two places where the list can drift. The step is complete when the written definition can be read by someone outside the project and turned into filter conditions without follow-up questions.
Build and test the report with the Advanced Pack
An administrator builds a list report in the Advanced Pack on the chosen entity, applying the filter conditions from the definition and limiting the columns to what the sync needs, such as the record ID and email address. Run the report under a test user with the same role the sync job will use, because report results depend on that user's access. The check is that the row count and sample rows match a manual filter applied in the list view for the same conditions.
Decide the sync mechanism
Choose between a scheduled job that refreshes the target list from the report on a set cadence, a workflow that adds or removes records when their fields change, or a manual refresh for small one-off campaigns. The choice depends on how quickly records must enter and leave the audience and on how often the criteria change. Record the decision with the reason, because it determines what the operations team must monitor later. The output is a short design note naming the mechanism and its owner.
Create the target list and exclusion lists
Create the target list for the campaign and separate exclusion lists for opt-outs, bounced addresses, legal holds or other suppression reasons, so each source can be audited on its own. Confirm which email marketing settings apply to each list and that the opt-out field used for exclusion is populated consistently in the imported and existing data. The check is a list view showing each list's name, purpose and owner, with no record appearing in the target list that is already on an exclusion list.
Configure the job or workflow and run a dry run
Configure the scheduled job or workflow to add report results to the target list and remove records that no longer match, with exclusion lists applied as a final filter. Before enabling it, run it in a test environment or against a copy of the data, and review the proposed additions and removals without sending anything. Background jobs in EspoCRM depend on cron or a scheduled task on the server, so confirm that this is running and that the job appears as completed in the scheduled job log. The check is a dry-run summary that matches the report row count minus the excluded records.
Verify removals and exclusions against a sample
Pick a sample of records covering each case: newly qualifying, no longer qualifying, and opted out. Confirm that records which stopped matching the report left the target list after a sync run, and that a record marked opted out never appears in the list even when it matches the criteria. Compare the sample against the report and the exclusion list manually, and keep the sample and results as evidence for the campaign owner. The sequence is complete when every sampled case behaves as the written definition says.
Run a test campaign before the live send
Send a test campaign to an internal seed group that includes an opted-out contact and a contact removed from the report, and check that neither receives the message. Confirm the recipient count in the campaign matches the expected figure from the dry run. Ask the campaign owner to sign off on the final list before the live send, and record who approved it and when. The output is a signed-off list and a test result that the operations team can reuse for later campaigns on the same audience.

How exclusion lists and opt-outs combine with synced audiences

A synced report can only be as clean as the rules applied to it. Exclusions and opt-outs decide who is actually mailed, so settle where they apply, how consent is recorded, how conflicts resolve and who approves the rules before the first sync runs.

Where the exclusion is applied

Exclusions can be applied while the target list is built, so suppressed contacts never enter it, or at send time, so the list keeps them but the campaign skips them. Filtering in the report keeps lists small and easy to review, but a later exclusion change will not remove people already synced. Filtering at send catches late changes but makes list counts look larger than what is mailed. Confirm which level your campaign feature enforces in your EspoCRM version before you design around it.

Opt-out status on contact records

Represent opt-out as explicit fields on each contact record, with a timestamp and a source such as a unsubscribe link, a sales conversation or an imported suppression file. A single boolean on a contact is easy to query but loses the history auditors ask for. Decide which process writes the field and which sources are allowed to clear it, because a re-import that sets the flag back to false can silently re-enable mailing.

Keeping opt-outs in sync

Opt-outs usually arrive from several places: the mailing tool, the CRM record, imports and manual edits. Map each source to one field, and run a scheduled check that compares suppression records against target list members before each send. Treat the most restrictive status as the winner. Test one opt-out from each source and confirm it disappears from the next sync.

Resolving conflicts between lists

A contact may match the audience report and also sit on an exclusion list, or be opted out while still meeting every audience condition. Set a written precedence rule: exclusion and opt-out always win, and the contact is logged as suppressed rather than dropped silently. Illustratively, a customer who asked to stop marketing emails should stay off a promotion list even if the report counts them as an active buyer.

Approval of suppression rules

Someone accountable for consent and marketing compliance should approve each exclusion rule, its precedence and who may edit opt-out fields. Engineering can implement the rule, but legal, privacy or marketing operations should confirm the wording and sources. Record the approver, the date and any changes, and review the rule set whenever the report, the campaign feature or the EspoCRM version changes.

When to use formula logic, workflows or an external job

A small team that needs an audience to reflect a field value, such as a marketing consent checkbox or a region, usually does not need a workflow at all. Formula Script, EspoCRM's built-in scripting language, can run in a before-save script configured in the Entity Manager, so a flag can be set or cleared whenever a record changes. The report then filters on that flag, and the target list is refreshed from the report results. The maintenance burden is low because there are only a few scripts, and the work stays in the core product. The skills needed are basic familiarity with EspoCRM fields and the Entity Manager, plus enough scripting comfort to read and test a short formula.

Build scope: one or two before-save formulas on the target entity, with the report filter defined in the admin interface.
Maintenance: review the formula when a field is renamed or a consent rule changes.
Skills: administrator knowledge of the Entity Manager and basic formula syntax.
Risk: a before-save script runs on every save, so a slow or broken formula affects everyday editing.
Limit: logic that depends on time, approvals or other systems is harder to express here.

Before committing, confirm with a test set of records that the flag changes as expected when a record is created, edited and imported.

Security and data handling for synced campaign audiences

A synced target list is only as trustworthy as the controls around it. The cards below cover who can change the report and list definitions, how an external sync authenticates, and how changes and exports are traced and limited.

Restrict who can edit audience definitions

Both the report that selects contacts and the target list it feeds are records with their own permissions. Decide which roles may edit report filters, change list membership or switch on a sync, and keep those rights away from general sales and marketing users. Review role assignments before go-live, because a user who can edit a report can change who receives the next campaign. Confirm the exact role permissions for reports and target lists in your EspoCRM version.

Use an API user with HMAC

An external system that pushes or pulls audience data should authenticate as a dedicated API user, not as a person. The EspoCRM API docs describe HMAC as the most secure of the supported methods and basic authentication as not recommended, so plan the sync around HMAC. Give the API user only the entity and read or write permissions the sync needs, and nothing that touches users, roles or settings.

Keep admin accounts out of scheduled changes

Scheduled report runs, list refreshes and any automation should not run under an administrator login. An admin account that is compromised or misused can alter every audience in the system. Use a restricted service identity for background work, and confirm which user each scheduled job executes as before you rely on it. Admin accounts should also avoid daily work, as the security docs recommend.

Trace who changed a segment

When a campaign reaches the wrong people, you need to know which user or integration changed the report filter, added records to a target list or removed an opt-out exclusion. Check how EspoCRM records changes to reports, list membership and the API user's activity, and whether those logs are retained long enough for your review cycle. Test the trail with a deliberate change in a non-production instance before you depend on it.

Limit personal data in exports

Report exports and list downloads often contain names, email addresses and phone numbers that are copied into spreadsheets and email tools. Decide which fields a report may expose, who may export it and where exported files may be stored. Mask or omit fields that the campaign does not need, and check that exported copies follow your retention and deletion rules. Consult your privacy team on the lawful basis for each audience.

Harden access to the instance

The audience logic depends on the surrounding controls working. The EspoCRM security docs recommend enforcing a password policy, requiring two-factor authentication, limiting auth token lifetime, disabling password recovery for admins and restricting access by IP address. Apply these to every user who can edit reports or lists, and record which of them your identity provider or instance settings enforce.

Common questions about syncing reports to target lists

What does it cost to sync EspoCRM reports to target lists?

The cost comes from the written scope, not from a standard price, and DeployOpen does not publish a price list. The main cost drivers are the number of report-driven audiences, how many exclusion and opt-out rules must be applied, how much of the target list logic already exists in your instance, and whether the Advanced Pack reports and workflows are already licensed. The Advanced Pack is included in all EspoCRM Cloud plans, and the open-source edition can be self-hosted for free, so your licensing path changes the baseline. Ask for a quote that separates design, build, testing and handover, and that lists what is one-time and what recurs.

How long does a build like this take?

Timing depends on scope, and the only reliable figure comes from a written plan agreed before work starts. The number of audiences, the complexity of the report filters, the number of exclusion lists, and the amount of data cleanup needed all move the schedule. Expect the design of consent and exclusion rules to take as long as the technical build, because those rules need sign-off from marketing and compliance owners. Ask for a timeline with named milestones and the review gates that must be passed before a sync runs against live campaign data.

What must our team provide before the work starts?

Your team needs to provide named owners for each audience and each exclusion list, written opt-out rules, and a clear definition of which report defines each segment. Engineers also need a test instance or sandbox, a sample of report output, and access to the admin roles that manage target lists and workflows. Without written opt-out rules and a decision on who approves changes, the build stalls at the point where records must be included or excluded. Confirm these inputs with your marketing operations and legal or privacy contacts before the kickoff.

Can an internal EspoCRM admin build this alone?

An experienced internal admin can often build a simple version alone, especially for one audience and one exclusion list. The harder parts are designing the sync logic so that it runs repeatedly without duplicating or dropping contacts, testing that opt-outs are honored in every path, and documenting the rules well enough that someone else can maintain them. If your admin also owns production configuration, separate the build from daily admin work and keep admin accounts out of routine use, as the EspoCRM security documentation recommends. A partner is most useful when the audience count is high, when you need an independent review, or when the admin team is small.

How do opt-outs and exclusion lists get enforced?

Opt-outs and exclusions should be enforced as explicit rules that run after the report results are collected and before the target list is refreshed, so that no contact can be added back by a later sync. The design usually covers which field records consent status, which exclusion lists are subtracted, and what happens when a contact appears in both an include and an exclude set. Test each rule with contacts that have been opted out, bounced or removed from a list, and keep a record of the test results for your privacy review. Confirm the consent rules with your legal or privacy team, because the technical design depends on the policy they approve.

What does ongoing maintenance look like after go-live?

After go-live, maintenance covers report changes when sales or marketing redefine a segment, updates to exclusion rules, monitoring of sync runs and background jobs, and checks after EspoCRM upgrades. Plan for regular review of audience counts against expectations, because a silent change in a report filter can shift who receives a campaign. Scheduled background jobs depend on cron or a scheduled task being healthy, so monitoring that path matters. Ask whether ongoing support is handled through a retainer or on a request basis, and which party owns changes to production rules.

What should we check before a campaign uses a synced list?

Check that the target list matches the report count you approved, that excluded and opted-out contacts are absent, and that duplicates are not created by the sync. Review a sample of contacts against their source records, and confirm that the list is refreshed at the time the campaign expects. Engineers should also confirm that the sync does not alter other target lists and that permissions allow only the intended roles to edit the rules. Record these checks as a repeatable runbook so that every campaign run follows the same steps.

What to confirm in your environment before you build

The sync mechanism depends on features and server behavior that vary by version and hosting setup. Treat each item below as a question to answer with the vendor documentation or a test instance before you commit to a design.

List-update action availability

Confirm whether your installed version offers a list-update action in reports or workflows that can add matching records to a target list. Check whether the action is available from the Advanced Pack's report and workflow screens, and whether it can be run on a schedule or only by hand. If the action is missing, the design needs a different trigger, such as a scheduled job or an API script.

Handling of removed records

Establish what happens to a target list entry when the underlying record no longer matches the report, is deleted, or is archived. Some designs only add people and never remove them, which lets stale contacts stay in campaigns. Test a deleted record and a record whose status changes out of the report criteria on a test instance, and note the result for each case.

Refresh frequency under your cron setup

Background jobs depend on the cron or scheduled task on your server. Confirm how often the sync can actually run given your cron interval, job queue and any other scheduled work competing for the same window. A sync that looks hourly on paper can lag if the queue is backed up, so measure the real delay between a record change and its appearance in the list.

Performance on large record sets

Test the sync against a copy of your production volume, not a small sample. Measure run time, database load and whether a large run blocks users or other jobs. Ask whether the process can run in batches and how it behaves if it fails halfway, since a partial update can leave a campaign with an inconsistent audience.

Opt-out and consent alignment

Check that the opt-out fields and exclusion lists EspoCRM uses match the consent records your legal and marketing teams hold. Map each field the campaign filters on to its source of truth, and confirm that an opt-out recorded in one place removes the contact from every target list. This is a legal question as well as a technical one, so have your compliance owner sign off on the mapping.

Behavior across your EspoCRM version

Report features, target list behavior and job handling can change between major releases. Confirm the exact behavior on the version you run and on the version you plan to move to, since an upgrade may change how the sync runs. Keep a test instance on the same version as production so each check reflects what users will see.

How DeployOpen scopes and delivers report-driven audiences

DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes the report-to-target-list work for EspoCRM campaigns. We agree the scope in writing before build starts, so your marketing, sales operations and security teams know exactly what the audience sync will and will not do.

How we scope

We confirm which reports feed each target list, the filter logic, and how often membership should refresh.
We document the exclusion lists and opt-out sources that must be applied before any campaign send.
We agree the written scope, deliverables and timelines with you before any work starts, since most engagements are fixed-scope.

How we build

We configure the report, target list and exclusion logic in your EspoCRM instance and test it against representative records.
We set up the scheduled refresh and verify that the Advanced Pack reports run under the API user or role you designate.
We run security testing on the access paths that expose contact data, including the roles and API users used for the sync.

How we hand over

We document each report, its filters, the refresh schedule, and the order in which exclusions and opt-outs are applied.
We walk your operations team through a test campaign audience check and a rollback step for a bad refresh.
We provide written records of the configuration so your team can audit who changed what and when.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, which covers changes to segments and exclusion rules.
We plan upgrades of EspoCRM and the Advanced Pack together, so report and target list behavior is retested before go-live.
We can prepare the access and configuration evidence your compliance reviewers ask for, though independent auditors issue any formal assessment.