Mautic Amazon S3 assets: what moves off the web server
The documented way to keep Mautic downloadable assets off the web server is the Mautic Amazon S3 plugin. The plugin hosts asset files in an Amazon S3 bucket, and when a user creates an asset in Mautic, they select the file from that bucket. For a self-hosted team, the practical change is that the files contacts download no longer need to be stored on the Mautic web server, which reduces what that server stores and serves. Everything else about how Mautic runs stays where it is today. Before you start, confirm that the plugin version you plan to use matches the Mautic release line you run, and read the plugin documentation for that version.
Several components stay on the Mautic server. The application, its database, contact records, segments, campaigns, forms and landing pages all remain in your Mautic installation. The cron jobs that update segments and campaigns and trigger campaign actions still run on the server, as do the broadcasts command and the messenger consumer when email is queued. The plugin changes where asset files are stored. It does not change how Mautic handles the requests that lead to a download. Confirm in the plugin documentation whether download links pass through Mautic or point directly to the bucket, because that decision determines what your web server logs, how access is checked and what your monitoring must cover.
The plugin does not change consent, tracking or preference settings. Marketing consent still lives in Mautic, so the GDPR considerations covered elsewhere in this set of pages apply regardless of where a file is stored. The plugin also does not make the bucket secure by default. Access policy, encryption settings and object versioning are AWS-side decisions that your AWS administrator owns. Asset files can contain personal data, such as personalized brochures or completed forms, so the bucket belongs in your records of processing and in your access review, even though it sits outside the Mautic server.
Three decisions come before configuration. The first is which AWS account and bucket will hold the assets, and who administers them. The second is the identity Mautic uses to reach the bucket. The setup guidance advises a dedicated IAM user and advises against using the AWS root account, so create a user with access limited to the bucket and to the actions the plugin documentation lists, and store its keys under your standard secrets process. The third is the bucket region. The documentation notes that the region matters for data protection and should be checked against your privacy policy, so confirm it with your privacy and legal contacts before you create the bucket, since moving objects later is additional work.
What you need before connecting Mautic to Amazon S3
Mautic assets on Amazon S3 depends on three layers working together: a supported Mautic installation on hosting the project accepts, an AWS account with a bucket you control, and a dedicated IAM identity that the plugin uses to read and write files. Settle the bucket region and its approver before anyone creates resources.
Mautic release and runtime requirements
The Mautic 7.0 requirements page lists PHP 8.2, 8.3, 8.4 or 8.5, MySQL 5.7 or higher with InnoDB or MariaDB 10.2 or higher, and Apache, Nginx or IIS as the web server. Confirm which release line you run before you choose a plugin version, because support windows differ between releases. Mautic 7.2 receives security support until 30 September 2026, and Mautic 7.3 is planned as the long-term support release. Record your current version so the upgrade path is part of the project plan.
Hosting the project accepts
The Mautic project states that Mautic should not be installed on shared hosting and recommends a VPS or dedicated server instead. Moving assets to S3 does not remove that requirement, because Mautic itself still runs on the web server and handles scheduled jobs there. Confirm with your provider that you have the root or sudo access, PHP and database versions, and cron and process control that Mautic depends on.
AWS account and bucket
Identify an AWS account that your organization controls, then create a bucket in the region your decision owner has approved. The plugin selects assets from this bucket when they are created, so the bucket becomes the storage target for every downloadable asset Mautic manages. Fix the bucket name, region and account owner before go-live, because moving existing objects later means updating references. Assign billing contacts and alerts that your team actively monitors.
IAM user instead of root
Mautic's S3 setup advises creating an IAM user for this work and keeping the AWS root account out of it. Root credentials cannot be scoped to a single bucket, so a leaked key would expose the whole AWS account. Create a dedicated IAM user for the plugin, grant it only the bucket actions the plugin documentation lists, store its access key in your secrets manager, and set a rotation schedule that your security team approves.
Bucket region decision owner
Mautic's S3 setup notes that the bucket region matters for data protection and should be checked against your privacy policy. Name one decision owner, usually from privacy or legal with input from the platform team, who approves the region and confirms that stored assets fit your published notices and transfer commitments. Record that approval with the bucket configuration so auditors and your own team can trace why the region was chosen.
Plugin compatibility with your release
The plugin version you install must match your exact Mautic release. Confirm compatibility in the Amazon S3 plugin documentation before you start, and repeat the check before every Mautic upgrade. Note the plugin version, Mautic version and PHP version in your change record. If the documentation does not list your release, ask the plugin maintainer or your implementation partner to confirm support before you install anything in production.
How the Mautic Amazon S3 plugin stores and serves assets
The Amazon S3 plugin changes where Mautic keeps downloadable assets. Instead of saving files on the local web server, the plugin hosts them in an S3 bucket. When a team creates an asset in Mautic, the file is chosen from that bucket, so the bucket becomes the storage location for those files from that point on. The web server still runs Mautic itself, but the asset files are no longer its responsibility to hold. That split affects backups, capacity planning and who can change or delete a file, so the team should map each step before enabling the plugin in production.
The documentation settles the basic flow, but several behaviors need confirmation before a go-live decision. The first is how existing local assets are handled once the plugin is active. Ask whether earlier files are migrated automatically, left on the server and still referenced, or must be re-created from the bucket. Test this on a copy of the production instance with a representative set of assets, and record which asset links break, change or keep working. Do not assume that older campaigns, landing pages or emails will pick up the new location without checking each one.
Access control is the second area to confirm. Teams need to know whether objects in the bucket are readable by the public, whether access depends on bucket policies or object permissions, and whether Mautic generates signed links that expire. These choices decide who can open an asset URL, how long a shared link stays valid and whether a leaked link exposes content. The S3 setup guidance recommends an IAM user instead of the root account. Give that user only the permissions the plugin needs on the target bucket, and document the policy so a security review can trace it.
The bucket region is the third decision. The guidance says the region matters for data protection and should be checked against your privacy policy. Confirm the region with your data protection lead before creating the bucket, because moving objects later means copying data and updating every stored link. Also decide whether access logging, versioning and backups for the bucket are enabled, since the plugin does not replace those controls. Before launch, run a pilot that creates, edits and deletes one test asset, and confirm that the resulting URLs, permissions and region match what your privacy and security documentation states.
How to configure the Amazon S3 plugin in order
This sequence moves a Mautic instance from local asset storage to a tested setup where downloadable assets are hosted in an Amazon S3 bucket. Each step ends with a check, so the team can confirm the region decision, the access model and the storage path before marketing depends on the assets. It assumes Mautic already runs and that an administrator can change plugin settings.
Confirm the bucket region with the privacy owner
Before any AWS resource exists, ask the privacy owner which region the asset bucket should use and confirm that the choice matches your organization's privacy policy. The Mautic guidance notes that the bucket region matters for data protection and should be checked against that policy, so treat the region as a decision that needs approval. Ask for the answer in writing, including the region code and any residency commitments that apply to files stored for marketing. This step is complete when the approved region is recorded in your change record and the privacy owner has signed off on it. Do not create the bucket until that approval exists.
Create the bucket in the approved region
Create one S3 bucket in the region approved in the previous step, using a name that makes its purpose clear, such as a Mautic assets bucket for a specific environment (illustrative). Keep public access blocked unless your review of the plugin documentation and privacy requirements shows that a different setting is needed, and confirm how Mautic will serve downloads before you publish any link. Enable the governance settings your organization requires, such as encryption or versioning, and record each one. The step is complete when the bucket appears under the approved region in the console and a test object you upload manually can be listed there. Delete that object afterward.
Create a dedicated IAM user for Mautic
Create a separate IAM user whose only purpose is Mautic's access to the asset bucket. The Mautic guidance advises using an IAM user rather than the root account, so do not generate root access keys or place root credentials in Mautic. Attach a policy that grants only the bucket and object actions the plugin needs on that one bucket, and confirm the exact action list in the plugin documentation for your Mautic version. Generate an access key for this user only and store it in your secrets manager. The step is complete when the policy simulator shows the user allowed on the asset bucket and denied on another bucket in the same account.
Install and enable the Amazon S3 plugin
On the Mautic server, install the Amazon S3 plugin using the same method your installation uses, and confirm that the plugin version is compatible with your Mautic release line. Then enable it from the plugin management screen in the Mautic admin area. Schedule this change in a maintenance window, because a failed plugin installation can affect the whole instance. The step is complete when the plugin shows as installed and enabled, and the Mautic logs show no errors after the change. Record the plugin version in your change log so it is checked during future upgrades.
Enter the connection details in Mautic
Open the plugin's configuration page in Mautic and enter the bucket name, the region code approved in the first step, and the access key for the dedicated IAM user. Check the field names and any optional settings against the plugin documentation for your version, because labels can change between releases. Keep the secret access key out of screenshots, tickets and shared notes. Save the configuration. The step is complete when Mautic reports a successful save and any connection test the plugin offers passes. If a field is rejected, check the region code against the bucket first.
Create a test asset from the bucket
Upload a small, harmless test file, such as a plain text document, to the bucket. In Mautic, create a new asset and select that file from the bucket, since the plugin chooses assets from the bucket at creation time. Save the asset. The step is complete when the asset saves and shows the bucket file as its source, and the web server's local asset folder does not gain a copy of the file. If a copy appears locally, stop and review the plugin configuration before creating more assets.
Test download from a non-admin session
Sign in to Mautic as a user without administrator rights, or open a private browser session with no administrator cookies, and retrieve the test asset through the link or form Mautic provides. Confirm that the file downloads and that its contents match the original. If your organization has enabled AWS access logging or CloudTrail for the bucket, check that the download appears there. The step is complete when the non-admin download succeeds and the result is recorded in the change ticket. Then delete the test asset and the test object.
Which Mautic asset fields map to which S3 settings
This table links each Mautic asset step to the AWS setting it depends on and names who owns that value. Read it before configuring the plugin, so each Mautic field is checked against the bucket, region, IAM user or object path it relies on. The main takeaway is that the region and the IAM user need sign-off from people outside the Mautic team.
| Mautic-side item | AWS-side setting it depends on | Who owns the value | What to confirm in plugin settings |
|---|---|---|---|
| Asset creation | Bucket name the plugin writes uploaded files to | Cloud team that creates the bucket | Bucket name matches the bucket you created, and a test asset uploads to it |
| Asset selection | Objects already in the bucket that Mautic lists when an asset is created | Cloud team (contents), Mautic administrator (selection) | The plugin lists objects from the configured bucket when you create an asset |
| Storage location | Bucket region, which the plugin docs tie to data protection | Cloud team, with privacy or legal review | Region matches the location your privacy policy describes for hosted data |
| Uploading user | IAM user whose access keys the plugin uses, and its permissions on the bucket | Security or cloud team | The plugin uses an IAM user, not the root account, and its permissions are limited to this bucket |
| Object key or path | Key under which each uploaded file is stored in the bucket | Mautic administrator and cloud team together | How keys are formed in a test upload, and that recipients can reach the file as your policy requires |
Security settings for Mautic assets in S3
Hosting Mautic assets in S3 moves files out of the web server, so the bucket and the identity that writes to it become the security boundary. The cards below cover the identity, its permissions, its credentials, the bucket location and the bucket's exposure settings, in the order a team would configure them. Confirm each AWS setting against current AWS guidance for your account before you rely on it.
Use an IAM user, not root
Mautic's S3 setup guidance advises creating an IAM user for the plugin rather than using the AWS account root user. The root account has unrestricted access to everything in the account, so a leaked key would expose far more than the asset bucket. Create a dedicated user for this plugin only, and confirm with AWS documentation that the root user has no active access keys in your account.
Scope permissions to one bucket
Attach a policy to the IAM user that allows only the object actions Mautic needs on the asset bucket, and nothing on other buckets or account services. Ask your Mautic implementer which actions the plugin calls in your version, then test uploads, downloads and asset selection against the policy. Review the policy whenever the plugin or Mautic is upgraded.
Store and rotate access keys
The plugin needs an access key ID and secret, which should be kept out of source control and out of shared configuration files that many administrators can read. Store them in your secrets manager or a restricted server configuration, and set a rotation schedule that your team can execute without downtime. Confirm the current AWS guidance on key age, key limits per user and deactivation before you set the schedule.
Choose the bucket region deliberately
Mautic's setup guidance notes that the bucket region matters for data protection and should be checked against your privacy policy. Asset files may contain personal data, such as forms, attachments or images tied to named recipients, so the location must match the jurisdictions your privacy notice describes. Record the chosen region and the reason in your data inventory, and confirm the region with legal or privacy owners before creating the bucket.
Check public access and encryption
Confirm that block public access settings are enabled at the bucket and account level, and that bucket policies and object ACLs do not grant anonymous read access. If assets must be reachable from the web, decide whether they are served through a controlled path rather than public object URLs. Also verify that default server-side encryption is enabled on the bucket, and check the current AWS settings for these options in your account.
How to test Mautic S3 asset delivery before go-live
Before a Mautic installation with the Amazon S3 plugin goes live, run a scripted test plan that follows one asset from upload to a contact's inbox. The goal is to prove that the object lands where your data protection decisions say it should, that a visitor can open it without an administrator's session, and that a campaign email still resolves the link after credentials change. Write the plan down with named steps, expected results and the person who signs off each one, so the same plan can be rerun later without rebuilding it from memory.
Start in the Mautic administration area. Upload a small test file, such as a plain text document, and select it as the asset source in the S3 configuration. The Mautic Amazon S3 documentation describes assets being selected from the bucket when they are created, so confirm that the asset record points to the bucket you intended rather than to the local web server. Then check the bucket in the AWS console or with the AWS CLI. The object should appear under the expected key prefix, in the bucket you configured, and in the region your privacy policy names. If the region in Mautic differs from the bucket's actual region, stop and correct it before continuing, because the Mautic setup guidance treats the region as a data protection setting, not a cosmetic one.
Next, test delivery the way a contact will experience it. Open the asset link in a private browser window that has no Mautic login session, then repeat the request from a second network if your visitors come from several locations. Confirm the file downloads with the correct name and content type, and that nothing in the link exposes the bucket's root path or account details. Record the exact URL pattern, the HTTP response and the time taken. If the link is signed or time-limited, note the lifetime so the team knows how long a delivered email will keep working.
Then test the failure and rotation cases, which are the ones teams usually skip. Deactivate the IAM access key used by Mautic, or replace it with a new key, and confirm the behavior you expect: whether the visitor sees an error, whether Mautic logs a clear message, and whether the existing asset record still resolves after the new key is saved. Restore the working key and retest. Finally, send a test campaign email that contains the asset link to an internal contact, open it on at least two mail clients, and click through. The link must still resolve after the key rotation test. Confirm with your mail provider's delivery logs that the message was sent, since a broken link often looks like a successful send.
Keep a dated test record with the Mautic version, PHP version, plugin version, bucket name, region, IAM user name (not the secret), each result and the tester's name. Repeat the full plan after any Mautic upgrade, after a plugin change, after every access key rotation and after any change to bucket policy or region. The Mautic releases page sets out the upgrade cadence, so plan the retest into each upgrade window rather than treating it as optional. Ask your implementation partner or internal team to confirm, in writing, which Mautic and plugin versions the test plan was built against, and whether your chosen signed-link behavior is supported on that release.
Why Mautic S3 assets fail to load and how to fix them
This table lists the most common reasons Mautic assets stop loading after they move to Amazon S3, with the likely cause, the check to run and the fix for each. Work through the rows in order, since access and region problems are usually the quickest to confirm. Where a permission or setting name matters, verify it against the Mautic Amazon S3 plugin documentation before you change production.
| Failure | Likely cause | Check to run | Fix and where to confirm |
|---|---|---|---|
| Access denied errors | The IAM user's policy is too narrow for the bucket actions the plugin needs | Compare the policy attached to the IAM user with the actions listed in the plugin docs, then test one upload and one read | Widen the policy to the required actions on this bucket only. Confirm exact actions in the plugin documentation. |
| Region mismatch | The region in the plugin settings differs from the bucket's region | Note the bucket's region in the AWS console and compare it with the plugin's region setting | Set the plugin to the bucket's region. Confirm region handling in the plugin documentation and your privacy policy. |
| Broken links after key rotation | The plugin still holds an access key that was rotated or deactivated | Check which key the plugin uses and whether that key is still active for the IAM user | Enter the new key in the plugin, test an upload, then deactivate and delete the old key. Confirm where the plugin stores credentials. |
| Older assets fail to load | Assets created before the change still reference the previous storage location | Open an asset created before the change and compare its URL with the current bucket and settings | Re-create or re-upload older assets, or keep the old location reachable during transition. Confirm migration steps in the plugin documentation. |
| Links break on public access | Bucket access settings block public reads, or object permissions do not allow downloads | Open an asset URL in a private browser window and review the bucket's public access settings and object permissions | Allow read access only for the objects meant for public download. Confirm required bucket settings in the plugin documentation. |
Questions teams ask before connecting Mautic to Amazon S3
How much does it cost to connect Mautic to Amazon S3?
The cost follows from a written scope, and DeployOpen provides a quote once that scope is agreed. DeployOpen does not publish a price list. The main cost components are the plugin configuration, the bucket and IAM design, testing of uploads and asset selection in each environment, and a handover of documentation. Ask for a quote that separates one-time work from anything recurring, such as credential rotation, monitoring or retainer support. Also ask which AWS charges your team will pay directly, because storage and data transfer are billed by AWS under your own account and are not part of a DeployOpen quote.
How long does an Amazon S3 asset setup take for Mautic?
The duration depends mainly on the number of environments, the volume of existing assets and how quickly decisions are made. A single production instance with no existing assets to move is the simplest case, and each additional environment adds configuration and testing. Migrating existing downloadable files adds inventory, copying and checking that campaigns and pages still reference the right objects. Decisions on bucket region and IAM design also set the pace, as does the availability of your test window. Ask for a timeline in the written scope that lists each of these factors and the dates your team must hold open.
What does our team need to provide before the S3 work starts?
Your team needs to provide AWS access, a region decision, a test window and Mautic administrator access. For AWS, the person doing the work needs permission to create or manage a bucket and an IAM user in the account that will own the assets. The region decision should be checked against your privacy policy before the bucket is created. The test window should cover non-production and production testing. Your team should also supply a list of existing downloadable assets and where they are used, along with a named approver for handling access keys and changes.
Can an internal team connect Mautic to Amazon S3 without a partner?
An internal team can do this alone if it has Mautic administration skills and someone who owns AWS identity and storage decisions. The plugin configuration itself is a bounded task, but the work also involves designing a least-privilege IAM user, storing and rotating access keys, choosing a region and verifying uploads and downloads across environments. Teams without recent AWS IAM experience often find the key management and verification steps take the most care. A partner can take on the whole piece or only the parts your team lacks, such as IAM review or testing. Compare both options against the written scope rather than against a general estimate.
Which Amazon S3 bucket region should we choose for Mautic assets?
Choose the region that matches what your privacy policy and data protection commitments say about where asset data is stored. Mautic's S3 setup guidance notes that the bucket region matters for data protection and should be checked against the privacy policy, so the decision belongs to your privacy and legal owners as well as the engineers. Record the decision and the reason in the project documentation before the bucket exists. Moving assets to another region later is a migration project of its own, so settling the region before the first upload avoids rework.
Why does the S3 setup use an IAM user instead of root credentials?
Mautic's S3 setup advises using an IAM user, because the root account has full control of the AWS account and should not be used for application access. An IAM user can be limited to the permissions the plugin needs for the bucket. Confirm the exact permissions against the plugin documentation for your Mautic version, then keep the policy narrow. Access keys for the IAM user need an owner, a rotation schedule and a removal step when people or systems change. Include these tasks in the handover so they continue after the project ends.
Does a later Mautic upgrade change the Amazon S3 asset setup?
An upgrade can affect the S3 setup, so check plugin compatibility with the target Mautic release before you upgrade. Mautic publishes monthly patch releases, minor releases every three months and major releases every two years, so the release line you run determines how often you will repeat this check. Before each upgrade, confirm the plugin supports the target version, retest asset upload, selection and download in staging, and confirm the IAM policy and bucket settings still match. Ask for the upgrade steps and the staging test to be included in the handover or in a retainer scope.
How do environment count and asset migration scope change the effort?
Each environment adds its own configuration, testing and access decisions, and each existing asset set adds migration and reference checks. Development, staging and production often need separate buckets or clearly separated prefixes, separate permissions and separate test passes. Migration scope grows with the number of files, their sizes, the number of campaigns and pages that reference them, and any assets that are no longer in use and should be removed first. Ongoing key management also grows with the number of environments because each set of credentials needs rotation and an owner. Ask any quote to state the number of environments and the migration boundary explicitly.
How DeployOpen scopes and delivers a Mautic S3 asset setup
DeployOpen plans and implements self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Mautic assets on Amazon S3, the work is agreed in a written, fixed scope before any build starts, then delivered and handed over with documentation your team can operate.
How we scope
- Confirm which Mautic instance and downloadable assets will move from the web server into the S3 bucket.
- Agree the IAM user, its permissions and how credentials are stored and rotated, rather than root account access.
- Record the chosen bucket region and check it against your privacy policy and data protection obligations.
How we build
- Install and configure the Amazon S3 plugin on your Mautic instance and connect it to the agreed bucket.
- Test asset creation so new files are selected from the bucket and served correctly to contacts.
- Verify that existing assets migrate or remain reachable, and that the web server no longer stores new uploads.
How we hand over
- Deliver a written configuration record covering the bucket, region, IAM user and permission scope.
- Document the steps to add or rotate credentials and to confirm the bucket region on future changes.
- Walk your operations and marketing owners through asset creation so the setup is understood after handover.
How we support
- Offer ongoing support, upgrades and checks as a retainer after the fixed-scope work is complete.
- Review the S3 plugin when Mautic moves to a new release line so the asset setup stays compatible.
- Confirm with your cloud and privacy teams any change to the bucket region or access model before it is made.
