mautic/mautic instruction manual

1. What Mautic is, evidence scope, and Claude Code classification

Mautic is a public PHP repository for self-hosted, open-source marketing automation. The project describes its purpose as helping businesses and organizations deliver integrated marketing campaigns. Its stated design goals are privacy, accessibility, and extensibility: operators can run the software themselves, use their own database, modify the frontend and backend, and create integrations suited to their environment.

**Claude Code classification: unclassified.** None of the supplied first-party files documents a Claude Code plugin, Agent Skill, MCP server, hook, command, instruction file, or other Claude-specific mechanism. It is therefore not reliable to classify Mautic as extending Claude Code or even as a documented Claude companion. Treat it as an independent marketing-automation application unless additional first-party evidence establishes a Claude relationship.

This manual is limited to the supplied repository metadata and first-party README files. The root README points to separate user, developer, API, installation, requirements, supported-version, troubleshooting, and contribution documentation, but those pages were not supplied. Consequently, this manual explains all functions actually described in the provided files, but does not invent screen-by-screen campaign procedures, API calls, configuration values, scheduled jobs, or deployment commands. Repository metadata identifies `7.x` as the default branch, while some README badges and links mention `6.x` or `head`; verify the branch and supported release through the project’s Releases and supported-versions pages before installation.

2. Documented marketing and platform functions

Mautic’s central function is **marketing automation**: coordinating integrated campaigns rather than requiring every step to be carried out manually. The supplied README does not document the individual campaign-builder controls, so use the linked user documentation for exact workflows.

Its documented capabilities are:

• **Self-hosted operation:** run marketing automation on infrastructure you control instead of depending entirely on a third-party SaaS service.
• **Data ownership:** use your own database and retain control of the data stored in it.
• **Segmentation and automation:** organize audiences into segments and automate marketing activity. The project describes these as unlimited, but the supplied files provide no performance limits or sizing guidance.
• **Multi-channel marketing:** manage activity across more than one channel without channel-based feature charges claimed by the project. Specific supported channels are not enumerated here.
• **Campaign creation:** build integrated campaigns without the feature limitations the README associates with conventional tools. Exact actions, triggers, and campaign controls are outside the supplied evidence.
• **Customization:** modify both frontend and backend behavior. This supports adapting presentation and server-side operation to local needs.
• **Integration development:** create integrations needed by an organization. No integration API example is present in the supplied files; consult the first-party developer and API documentation rather than guessing endpoints.
• **Portability:** modify or switch away from the software, avoiding the vendor lock-in described by the project.

These are platform-level functions, not promises that every deployment is automatically private, secure, or cost-free. Infrastructure, database, operational, integration, and maintenance responsibilities remain with the operator when self-hosting.

3. Choose between a trial, production package, and repository source

The README presents three ways to begin, each intended for a different purpose.

**Hosted trial:** use the project’s “Request a trial” link, fill in the form, and wait for the instance to deploy. This is the documented route for evaluating Mautic within minutes without first assembling a local environment. No trial duration, data-retention policy, price, or service guarantee is supplied, so review the trial terms before entering real contact data.

**Production self-hosting:** use the pre-packaged production download from `https://www.mautic.org/download`, or follow the linked Composer installation documentation. The README recommends Composer or the production package for production environments because the package includes the required libraries. Before choosing a package, check the Mautic Releases page, installation requirements, and supported versions.

**GitHub source:** reserve this route for local development and testing when you are comfortable with command-line maintenance. The repository explicitly warns that source outside a tagged release is alpha-quality and may contain bugs or cause unexpected behavior, data corruption, or data loss. It also warns that source and database-schema drift can prevent the release updater from working and force manual updates.

Do not treat the default branch as a production release merely because it is public. Select a supported, tagged release for stability. The supplied documentation does not provide a backup, upgrade, rollback, web-server, database, mail, or cron procedure, so those steps must come from the linked first-party installation and administration documentation.

4. Source installation: prerequisites and supported copy-paste commands

For the repository-source route, **Composer must already be installed**. Composer downloads the vendor packages required by this development release. The supplied README does not state supported PHP, database, web-server, Composer, Node.js, or operating-system versions; check the linked requirements and supported-versions pages before proceeding.

For a ZIP-based local installation:

1. Download the repository ZIP using the GitHub download link and extract it into the intended web root. The README also mentions bringing it in through Composer, but the actual command is missing from the supplied text, so none is reproduced here.
2. From the extracted project directory, install required packages:

composer install

1. Open the application in a browser and complete setup with the web installer.

A DDEV configuration is present in the repository. If the project has already been configured for DDEV, the documented start command is:

ddev start

The README also documents an explicit configuration-first sequence:

ddev config
ddev start

DDEV starts the first-run process, which the README says automatically installs dependencies and configures Mautic for use. These commands are alternatives based on the local DDEV state, not additional production deployment instructions. DDEV itself must already be installed. Do not add undocumented flags or substitute guessed container commands. For production, follow the linked Composer guide or use the pre-packaged release rather than treating this short development procedure as a complete production runbook.

5. First run, control of data, customization, and bundled themes

After dependencies are installed through the ZIP workflow, open Mautic in a browser and finish the **web installer**. The supplied README does not show the installer fields, defaults, database permissions, administrator-account requirements, mail settings, or URL configuration. Enter values appropriate to your own environment and consult the official installation requirements rather than relying on assumed defaults.

A self-hosted installation is intended to use your own database and keep operational control of marketing data. That makes you responsible for access control, backups, upgrades, retention, recovery, and the lawful handling of contact information. The project’s privacy-focused vision describes an objective, not an automatic guarantee for every configuration or integration.

Mautic is documented as customizable on both the frontend and backend, and as able to support newly created integrations. The supplied files do not include safe extension procedures or API examples, so make such changes through the developer documentation and test them away from production data.

The repository includes README evidence for these named themes: **Blank, Cards, Aurora, Oxygen, Sparse, Sunday, Survey** (`themes/_survey`), **Attract, Skyline, and Vibrant**. These files establish that the themes exist and are centrally managed in the main `mautic/mautic` repository; they do not document activation, configuration, layout options, or compatibility. Each theme README calls its corresponding theme location a read-only mirror and directs issues and pull requests to Mautic Core. Therefore, do not submit changes to a separate mirror when the intended contribution belongs in this main repository.

6. Repository organization and contribution workflow

The `app/README.md` identifies the application core library as centrally managed from the main Mautic repository and describes its separate location as a read-only mirror. Likewise, every supplied theme README directs development activity back to Mautic Core. In practical terms, use `mautic/mautic` as the central place for relevant issues and pull requests rather than filing against mirror repositories.

The project offers several documented entry points for contributors:

• “Easy-to-fix bugs” for approachable defect work.
• Pull requests identified as suitable for testing.
• Low-code and no-code tasks for contributors who are not making substantial source changes.
• The contributing guide and “Contributing Code” documentation for asking questions, creating issues, and submitting pull requests.

No contributor setup or test command appears in the supplied files, so this manual does not invent one. Read the linked contribution guidance before opening a change. The project states that participants are governed by its Code of Conduct.

For ordinary defects and feature discussions, use the public GitHub issue tracker. Do **not** put undisclosed security details into a normal public issue. The README instead directs security findings to GitHub’s private security-advisory form and the repository security guide.

The long contributor table records many forms of participation, including code, testing, documentation, pull-request review, bug reports, accessibility, design, translation, tutorials, talks, event organization, and project management. This demonstrates that useful contribution is not limited to PHP development. However, the supplied README is truncated partway through that table, so it should not be treated as a complete current contributor roster.

7. Maintenance, security, privacy, licensing, and operational cautions

Repository-source installation carries explicit maintenance risk. The project warns that GitHub source requires continued command-line work and that mismatches between source and database schema can break the release updater. Untagged code is described as alpha and potentially capable of unexpected results, corruption, or loss. Use tagged, supported releases; maintain tested backups; and plan upgrades through first-party release documentation. Backup and rollback commands are not present in the supplied evidence and therefore are not provided here.

Self-hosting avoids mandatory dependence on a third-party SaaS and gives control over the database, but it also transfers responsibility to the operator. Protect administrator access, infrastructure, integrations, and stored contact data. Review the behavior and privacy terms of every external service you connect. The supplied files do not document encryption, authentication controls, telemetry, retention defaults, email-delivery safeguards, consent management, or regulatory compliance, so no claims about those areas should be inferred.

Report suspected vulnerabilities privately at:

`https://github.com/mautic/mautic/security/advisories/new`

Also consult `https://github.com/mautic/mautic/security` for the project’s security guidance. Use public issues for non-sensitive bugs only.

The README calls Mautic open source and says it can be used for free, while supplied GitHub metadata reports the license as “Other” with SPDX identifier `NOASSERTION`. That metadata is insufficient for a precise legal summary. Inspect the repository’s actual license files and applicable package licenses before redistribution, modification, or commercial deployment. Similarly, project statements such as “unlimited” segmentation and automation are positioning claims; the supplied files contain no capacity measurements, infrastructure sizing, or service guarantees.

8. Help, authoritative references, and a safe quick-start checklist

Use the project’s first-party support routes according to the type of question:

• **User documentation:** `https://docs.mautic.org` for operating Mautic and its marketing features.
• **Developer documentation and API reference:** `https://devdocs.mautic.org` for supported customization and integrations.
• **Forum:** `https://forum.mautic.org/` for community troubleshooting and prior discussions.
• **GitHub Issues:** `https://github.com/mautic/mautic/issues` for reproducible repository defects and development tracking.
• **Downloads:** `https://www.mautic.org/download` for the production package.
• **Project site:** `https://www.mautic.org` for project information, trials, community channels, blog, and strategy updates.

A source-supported local evaluation checklist is:

1. Decide whether a hosted trial is sufficient; avoid entering sensitive production data until its terms are understood.
2. For self-hosting, check Releases, requirements, and supported versions before downloading anything.
3. Prefer a supported tagged production package or the documented Composer production route.
4. Use GitHub source only for local development or testing; have Composer available.
5. If using the ZIP workflow, extract it into the web root, run `composer install`, then complete the browser installer.
6. If using the repository’s DDEV setup, run the documented `ddev start`, or `ddev config` followed by `ddev start` when configuration is needed.
7. Keep source and database schema aligned during updates, and rely on first-party upgrade instructions.
8. Use public support channels for ordinary problems and the private advisory form for security findings.

No supplied evidence documents Claude Code use. Do not install or configure this repository as a Claude extension without separate first-party instructions.