EspoCRM data retention and cleanup settings guide

EspoCRM data retention and cleanup settings: what the platform covers

EspoCRM's cleanup settings control how long certain artifacts are kept, but they do not define your retention policy and they do not make your deployment compliant. If you run a self-hosted EspoCRM that holds customer personal data under the GDPR, the platform helps you align deletion with the periods your policy sets, while the policy itself, the lawful basis for keeping each category of data and any certification or audit are your responsibility. The GDPR, Regulation (EU) 2016/679, does not prescribe fixed retention periods in its text for every record type; it requires controllers to apply appropriate security of processing under Article 32 and to justify how long personal data is held. It sets no audit or certificate requirement, and certification under Article 42 is voluntary.

The topic facts cover five groups of artifacts that EspoCRM's default configuration cleans up on a schedule run by cron. Deleted records are permanently removed after two months under the cleanupDeletedRecordsPeriod parameter. Export, mail merge and mass PDF attachments are cleaned up after 15 days, notifications after two months, and upgrade file backups are kept for two months. The EspoCRM config parameters page lists the keys and their defaults. Confirm each value against the version you run, because defaults can differ between releases and the page is the reference for your installed build.

Other artifacts that matter for evidence sit outside these settings and need their own decisions. Audit history, the auth log, action history and the stream are not covered by the cleanup list above, so check how long they persist in your instance. Database and file-system backups, server logs, reverse proxy logs and copies held by mail servers or identity providers are also outside EspoCRM's configuration. Before you set any value, document the retention period for each category, decide who approves a shorter or longer period, and confirm with your legal or privacy team whether the default two-month window for deleted records is too short to support an erasure or incident investigation.

Which retention requirements map to which EspoCRM settings

This table compares common retention obligations with the EspoCRM cleanup settings that remove data automatically, and the defaults that apply unless you change them. Read each row as a question to answer before go-live: which period your policy sets, and whether the default removes evidence you still need. Confirm every retention period with your legal or privacy counsel before you rely on the defaults.

Requirement	EspoCRM capability	Configuration key and default	What to confirm
Security of processing (GDPR Article 32): keep evidence that access and changes to personal data were controlled	Deleted records are purged by a scheduled job, so the record and its history disappear	cleanupDeletedRecordsPeriod, default 2 months	Whether a longer or shorter purge period matches your policy, and whether audit evidence must outlive the record
Breach notification (GDPR Articles 33 and 34): reconstruct what data was affected and when	Notifications are removed after a set period, which can remove the trail of alerts sent to users	Notification cleanup, default 2 months	Whether your incident timeline depends on notifications older than two months and where else that history is stored
Breach notification (GDPR Articles 33 and 34): reconstruct what data was exported or merged	Export, mail merge and mass PDF attachments are removed automatically	Export, mail merge and mass PDF attachment cleanup, default 15 days	Whether exported files containing personal data should be removed sooner, or retained longer under a documented process
Security of processing (GDPR Article 32): recover a system after a failed upgrade	Upgrade file backups are kept so you can roll back a failed upgrade	Upgrade file backup retention, default 2 months	Whether backups containing personal data fall under the same retention rules as the live system
Retention policy: remove personal data once the purpose ends	Cleanup jobs only act on the periods above; they do not delete active records or attachments on a schedule you define	Cleanup periods listed above; review each in the config parameters	Your retention schedule per entity, and which records need a separate deletion or anonymization process

Where EspoCRM defaults delete evidence too early

EspoCRM ships with cleanup periods that remove several kinds of data automatically after fixed intervals. Some of that data is operational clutter, but some of it is the only record of a deletion, a mailing or an upgrade path. Review each default against your own retention policy before the first cleanup job runs.

Deleted records after two months

Records marked as deleted are kept for a period and then removed permanently by the cleanup job, governed by the cleanupDeletedRecordsPeriod parameter. That deletion is often the only proof that a customer record existed, was removed and when. If your policy requires an erasure trail or a record of disposal, the default period may remove that evidence before your own review cycle. Confirm the window in your instance's config and decide where the disposal log will live instead.

Export files after 15 days

Export, mail merge and mass PDF attachments are cleaned up after a short default period. These files are the exact output that a user sent to a customer, a printed quote or a contract batch, so they can be the simplest proof of what a person received. If a dispute arises weeks later, the file may already be gone and only the database fields remain. Decide whether these outputs belong in your records or are disposable working copies, and set the period to match.

Mail merge and mass PDF attachments

Mail merge and mass PDF files are generated in bulk and then removed by the same short cleanup. A mass PDF sent to a customer base may be the only copy of the exact wording and terms delivered at that date. Once the attachment is removed, you can still see that a send happened, but not what the recipient saw. If your policy treats outgoing communications as records, store copies in a document system outside the cleanup path.

Notifications after two months

Notifications are removed after two months by default. They record who was told about an assignment, a status change or a due date, which can matter when you need to show that a responsible person was alerted. Notifications are also not the same as the audit trail, so do not assume a stream entry or audit log replaces them. Check whether your investigations or service-level reviews depend on notification history, and align the period or export it before cleanup runs.

Upgrade file backups after two months

Upgrade file backups are kept for two months by default, and they give you a rollback path if an upgrade fails or a customization breaks after the release. Once they are removed, the rollback path depends on your own backup of the application files and database. Upgrade backups also show the code state before a change, which can matter for change management reviews. Confirm that your infrastructure backups cover the application directory independently of this cleanup.

How cleanup settings differ for self-hosted and cloud deployments

In a self-hosted deployment, your team owns every cleanup setting and every copy of the data. EspoCRM's configuration parameters carry the defaults that matter most: records marked as deleted are permanently removed after 2 months (cleanupDeletedRecordsPeriod), export, mail merge and mass PDF attachments are cleaned up after 15 days, notifications after 2 months, and upgrade file backups are kept for 2 months. These values only take effect when the scheduled jobs run.

Cron is the trigger. The server configuration docs require cron or a scheduled task for background jobs. If cron stops, cleanup stops too, and deleted records or attachments can outlive your policy without any visible error. Check the scheduler on the server and do not assume it is running.
The config file is yours to control. Changes to cleanupDeletedRecordsPeriod and related keys are made on your server, so they need change control, version history and a named owner.
Backups hold what cleanup removed. Database and file backups keep copies of records the application has already deleted. Backup retention, set in your backup tooling, decides how long that evidence survives. The installation script's command.sh utility handles backups, restores and upgrades, so confirm what it retains and where.
Upgrades create their own backup window. Upgrade file backups default to 2 months. Keep them only as long as your policy needs upgrade evidence.
Test before you trust. Delete a record in a non-production copy, then confirm it disappears after the configured period.

Before you write any period into policy, verify cron, the config file, backup retention and a test deletion on your own instance.

How the cleanup jobs run and when they fire

Cleanup only happens when the scheduler runs. On a self-hosted EspoCRM instance, the periods you set for deleted records, attachments, notifications and upgrade backups are enforced by background jobs, and those jobs depend on cron or a scheduled task calling the application on a regular basis. If the cron entry is missing, has stopped after a server move, or is failing silently, the configured periods are not enforced and data stays longer than your policy says. Treat job execution as a monitored control: confirm that scheduled jobs are running on a schedule, alert when they stop, and check the job queue after any change to the host, PHP version or container setup.

The clocks are sequential and they are not identical. A record marked as deleted stays in the database until the cleanup period for deleted records has passed, and only then is it permanently removed. Attachments from exports, mail merge and mass PDF generation follow a separate, shorter period, and notifications have their own. Because each item runs on its own clock, one deletion can leave several copies of the same information in different places for different lengths of time. Before you rely on any of these periods, confirm the exact values and the order of operations for your version (10.0.x) in the EspoCRM config parameters documentation, and test them on a non-production copy by deleting a sample record and recording when each artifact disappears.

Write down the answers to three questions before you change any value: how long the business and legal owner needs deleted records to remain recoverable, which evidence (such as notifications or upgrade backups) must survive an incident or audit, and who approves a shorter or longer period. Then record the chosen values in your retention standard and set a recurring check that compares the live configuration with that record. Any change to a cleanup period should also be reviewed against the audit and consent evidence that depends on it, since a short period can remove the only copy of a change history before anyone looks at it.

Configuring cleanup settings against your retention policy

This sequence turns a written retention schedule into tested EspoCRM cleanup periods, so each artifact class is kept as long as policy requires and no longer. It ends with a documented decision for every period.

Obtain the written retention schedule
Ask the data owner and counsel for a written retention schedule that names each record type, its purpose, the minimum keep period and the trigger that starts the clock, such as account closure or last contact. Ask whether any legal hold applies to customer records, mail or logs. The step is done when the schedule is signed off by the data owner and you can point to the version you will implement.
List each EspoCRM artifact class
Map the schedule against the artifacts EspoCRM keeps: deleted records, export, mail merge and mass PDF attachments, notifications, upgrade file backups, and any logs or audit data your deployment retains. Note which artifacts hold personal data and which hold evidence you may need later. The output is a table with one row per artifact class and a column for the policy requirement that governs it.
Record current configuration values
Read the current cleanup values from the administration settings or the config file in your installation, and record them with the date and the instance name. The default parameters include cleanupDeletedRecordsPeriod, which permanently deletes records marked as deleted after 2 months, and periods of 15 days for export, mail merge and mass PDF attachments, 2 months for notifications, and 2 months for upgrade file backups. Confirm the values you find against the config parameter reference, because your instance may already differ from defaults.
Set periods to match the schedule
Change each period so it matches the schedule row for that artifact class, editing the setting through the administration interface where it is offered or in the config file where it is not. Where the schedule requires evidence to survive longer than a default, such as audit data, make the change deliberately and record why. Where a period is shorter than policy requires, treat it as a finding and not as a saving. Done when the recorded values equal the schedule decisions.
Confirm scheduled jobs are running
Cleanup happens only when background jobs run, so confirm that the cron job or scheduled task that EspoCRM requires is installed, runs under the expected service account, and completes without errors in the logs. Check the job timestamps after the first scheduled window. If cron is not running, no cleanup period takes effect, and an instance can keep deleted records far longer than the settings suggest.
Test a deletion in a staging copy
Restore a copy of production into a staging environment, mark a set of test records as deleted, shorten the period in staging only, and wait for the scheduled job to run. Confirm which records, attachments and notifications are removed, and which remain, such as upgrade backups held outside the cleanup window. Keep the test evidence, including timestamps and record counts, so the result can be repeated after future upgrades.
Document the decision for each period
Write one decision record per artifact class that states the policy requirement, the old value, the new value, the reason, the person who approved it and the date. Include the backup and restore consequence, because a restore from a backup may bring back records that were already cleaned up. The sequence is complete when the records are stored with the retention schedule and reviewed when the schedule or EspoCRM version changes.

Evidence to keep before cleanup removes it

EspoCRM's default cleanup periods remove deleted records, attachments, notifications and upgrade backups on a fixed schedule, so the evidence that shows how your retention was set and applied has to be captured before those jobs run. The cards below cover the records to keep and the checks that show your schedule was followed. Whether they are sufficient for your assessment is a question for your auditors, not DeployOpen.

Written retention schedule with approval

Keep a retention schedule that lists each EspoCRM data type, its cleanup period, the legal or business reason for it, the named approver and the approval date. Each cleanup setting should trace back to a line in this schedule. Check that the schedule covers deleted records, attachments, notifications, logs and upgrade backups, because a period nobody approved is hard to defend when a security-of-processing question comes up under Article 32 of the GDPR.

Config snapshot before and after changes

Export the configuration file before and after every change to a cleanup parameter, and store both copies with the date and the person who made the change. Without these snapshots you cannot show what the value was on a given date, which matters when someone asks why records from a particular period no longer exist. Compare the two files and confirm that only the intended keys changed.

Cron job logs showing cleanup runs

EspoCRM needs cron or a scheduled task for background jobs, so cleanup only runs when that scheduler runs. Keep the scheduler logs and the application logs that show when cleanup jobs executed and what they removed. These logs show whether the configured periods were applied in practice, and they reveal gaps where cron stopped and cleanup did not run as planned.

Staging test record

Create a test record in a staging instance, mark it deleted, and watch it through the cleanup period you plan to use. Record the time it was removed and whether attachments, notifications and related entries disappeared with it. This test shows the real behavior of your version and settings, so the schedule is based on observed results rather than on documentation alone.

Change tickets for each period

Open a change ticket for every increase, decrease or new cleanup period, recording the reason, the requester, the approver and the rollout date. Link the ticket to the config snapshot and the staging test. Tickets turn an undocumented setting into an accountable decision, and they also show who was responsible when a shorter period was introduced and evidence disappeared sooner than expected.

Export taken before deletion

Before a cleanup period is shortened or an upgrade removes backups, take an export of the records, attachments and audit-relevant data that you must keep for a longer period under your schedule. Store the export in a location with its own access controls and retention rule. Confirm with your legal or compliance team which copies they need, because cleanup removes data from the application but may not remove copies you have already exported.

Questions buyers ask about EspoCRM retention and cleanup

How long does it take to align EspoCRM retention settings with our policy?

The duration depends on how many artifacts your policy covers and how many systems hold copies of the same data. Aligning the core cleanup parameters in a single EspoCRM instance is a short configuration task, but a complete alignment takes longer once you add custom entities, custom attachment fields, integrations that copy records, and evidence requirements that span cron logs, backups and mail systems. Ask any partner for a duration only after they have read your written retention schedule and inventoried the artifacts. In a fixed-scope engagement, the written scope sets the timeline, so the first deliverable is usually the inventory and the mapping from each policy category to a configuration key or an external process.

Can our own team align EspoCRM retention without a partner?

Yes, for a simple instance with a short list of policy categories. The main cleanup periods are set in the configuration file and can be reviewed with the EspoCRM config parameters documentation. The work becomes harder in three places: confirming that scheduled jobs actually run through cron, making sure upgrade backups and database backups follow the same deletion logic your policy describes, and proving to an assessor what was deleted and when. If your team already runs EspoCRM operations confidently and has a staging copy to test against, handling the configuration in-house is realistic. If you need multi-system evidence, a partner can help define the procedure and test it.

What do we need to provide before a retention engagement starts?

Four inputs make the work predictable. First, a written retention schedule that lists each data category, its retention period, and the trigger for deletion. Second, read access to the EspoCRM configuration and the server where cron, backups and logs are kept. Third, a staging copy of the instance that mirrors production configuration, so changes can be tested without deleting live records. Fourth, a named owner who signs off on the final periods and on the exceptions, such as legal holds or evidence needed for an audit. Without a named owner, the schedule tends to stall because nobody can decide whether a 15-day or 2-month period is acceptable for a given artifact.

What drives the cost of a fixed-scope EspoCRM retention quote?

DeployOpen does not publish a price list. A quote follows from the written scope, and the scope is shaped by the same factors that drive effort: the number of retention categories, the number of custom entities and attachment fields, the number of integrations that copy or hold records, the evidence you must keep and for how long, and whether backups live in systems you also need to configure. Recurring costs are separate from the one-time alignment work and depend on whether you later want a retainer for testing or upgrades. When requesting a quote, ask for the deliverables listed separately, the environments included, the testing method, and what evidence each deliverable produces.

Does GDPR require a certificate for our EspoCRM retention setup?

No. The GDPR requires no audit, attestation or certificate. It sets obligations for controllers and processors, including security of processing under Article 32, and leaves the way you demonstrate them to you. Certification under Article 42 is voluntary, is issued for at most three years by accredited certification bodies or supervisory authorities, and does not reduce the responsibility of the controller or processor for compliance. What the regulation expects is that your retention decisions are justified, applied consistently and documented, so you can show a supervisory authority how personal data was kept and removed.

Does DeployOpen certify that our EspoCRM instance is compliant?

No. DeployOpen plans, implements, configures and documents self-hosted open-source platforms, and prepares systems, controls and evidence for compliance assessments. It does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. In practice, a retention engagement delivers a documented schedule, the configuration applied, test results and an evidence procedure, which your assessor or data protection officer can review. Ask any partner to state in writing which outputs are evidence for your assessor and which are not.

What goes wrong if cleanup periods run before our policy allows?

The most common failure is deleting evidence before it is needed. Defaults can remove deleted records after two months, export, mail merge and mass PDF attachments after 15 days, and notifications after two months. If an investigation or access request arrives later, the material may already be gone. The reverse risk also exists: periods set too long can keep personal data longer than your policy justifies. Test each period on a staging copy, record the decision and owner, and confirm that backups follow a schedule consistent with the rest of the policy.

How DeployOpen scopes and delivers retention configuration and evidence

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including EspoCRM. For retention and cleanup, we start from your written retention policy, configure the cleanup periods that match it, and make sure the evidence you need is kept long enough to answer audits and incidents.

How we scope

Written scope lists each cleanup period, record type and environment (production, staging, backups) covered by the engagement.
We collect your retention policy and the owners who approve each period before any configuration changes are made.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.

How we build

We review the current EspoCRM config parameters and record each default against your agreed period.
Changes are made in a staging instance first, then tested with deleted records, attachments and upgrade backups.
We test that evidence sources such as the audit log and auth log still hold the entries your policy requires.

How we hand over

You receive a retention register mapping each setting to the policy clause it implements and its owner.
Runbooks cover how to change a cleanup period, how often to review it and what to check before an upgrade.
We document which items are outside EspoCRM settings, such as external backup storage, so your team can manage them.

How we support

Ongoing support, upgrade reviews and periodic retention checks are available as a retainer after handover.
Retention settings are rechecked when EspoCRM upgrades change defaults or when your policy is revised.
Confirm with your legal or compliance team how long evidence must be kept before we finalize the periods.

EspoCRM data retention and cleanup settings