mautic/mautic-documentation

User documentation for the Mautic project

Mautic Documentation

Introduction

⚠️ Please make new contributions against https://github.com/mautic/user-documentation as this repository will soon become deprecated

This serves as the documentation for Mautic, the open source marketing automation system.

Everyone is welcome to contribute to improve this information as needed.

Mautic Developer documentation

If you are looking for details about the Mautic API, webhooks, theme or plugin development, please see the developer documentation.

Contributing to the Mautic documentation

See CONTRIBUTING

License

The Mautic official end user documentation is licensed under the Apache 2.0, a permissive license whose main conditions require preservation of copyright and license notices. Read more.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Max Lawton 📖	Miami City Man 📖	Déborah Salves 📖	Adrian Schimpf 💻 📖	Rahul Shinde 📖	chartist1 📖	Robin Cafolla 📖
Jonathan Dahan 📓	SphinxKnight 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

mautic-documentation's Issues

Make a list of all required PHP modules

Inspired by this old, closed Mautic issue I think it would be a good idea to have a list of the required PHP modules somewhere in the Documentation - the docs mention the required PHP version, but not what extensions should be enabled. There is an extensions check done during installation, as the Getting started mentions in passing, but it would be nice to have a list somewhere in the docs so we don't have to go digging in app/bundles/InstallBundle/Configurator/Step/CheckStep.php to find it 🙂

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Redo gif in campaign builder page

It's totally tiny!

Improve/tidy images on Maxmind article

We pulled this together quickly, I would like it if we could improve the images and agree on a standard way that we highlight images.

https://docs.mautic.org/en/setup/maxmind-license

Documentation is missing for users and roles

When working on testing mautic/mautic#5995 I realised that we do not currently have any documentation on users and roles.

I think this should sit under the Setup section, or maybe its own section.

I'll write a basic page but we should probably expand on it.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Second Focus item won't trigger

Holly mother of Dragons, wrong board. Too many tabs opened, sorry guys! Please close this issue :)

Add information to Gated Video documentation

As mentioned in mautic/mautic#7365 (comment), we need to make it clear that folks can use the <video> element only with proper <source> elements to use the Gated Video feature. Please read the comment for all details.

missing email dynamic content doc

Hi @dongilbert, could you please work on Email dynamic content documentation ? mautic/mautic#2574

Thanks a lot for you help.

N.

documentation wrong for Salesforce

I used docs.mautic.org/en/plugins/salesforce#custom-fields-relationships
but it return error “No such column ‘WhoId__c’ on sobject of type mautic_timeline__c”
Then I found another manual mautic.com/help/salesforce-integration-setup and then I setup field: WhoId : Lookup(Lead)
Then works properly.
Form submit actions save in the right column

Can somebody from education team update the docs?

Broken link in the Salesforce CRM plugin documentation

Hey, just a quick note to say that the 'these steps' link here is currently 404. It should be fairly easy to fix if somebody knows there the steps moved to :)

Add information to explain that plain text version will be automatically created

With the merging of mautic/mautic#8645 the plain text email will be automatically generated if it is not provided.

We should add this information as a tip on the email page and merge the PR when we release 3.1.

Create a 'configuration' section

Something I noticed when I was suggesting that a new pull request needed to update the documentation is that we don't actually have a section which explains all the different parts of the configuration.

I wonder if this might be more helpful for a user than having this information scattered across all the different documentation sections.

Setting up Mautic, most of the time you will work through the configuration step-by-step, so I feel like it would be more helpful if this information was all in one place and we use deep linking to hook people into the relevant section using the header anchor tags when they are elsewhere in the documentation.

For example if I'm in the email section and mention about the bounce settings we could just link to the header in the configuration > email settings section.

What do you folk think?

Totally open to discussion!

Update docs to support Mautic 3

There are some commands that change in Mautic 3.x which we need to be updated across the documentation.

We will need to add a statement on the top of the page explaining that in Mautic 2.x use this version in Mautic 3.x use that version or something similar.

See this for a full list of updates, we are mainly interested in the user facing updates.

Update documentation to include recommended hardware specifications

Please DO NOT report security vulnerabilities here. Send them to [email protected] instead.

What type of report is this:

Q	A
Bug report?
Feature request?
Enhancement?	X

Description:

A number of queries in Slack and on the forums have been related to Mautic performance. It would be good to establish a "minimum hardware requirement" for Mautic to provide recommendations in future.

I suggest that we provide specs for the following use cases:

1. up to 500 contacts, two campaigns
2. up to 2000 contacts, 5 campaigns

3. 5000 contacts, 10 campaigns

If those numbers look wrong, please correct them - I'm happy to look at how we might test this etc.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Add information to contact preference centre page

While I was doing testing for the M3 beta I was trying to send an email and force people to go to the preference centre rather than to unsubscribe directly.

It was not clear to me from the documentation that you needed to enable the global configurations settings relating to preference centres in order for this to be included rather than the unsubscribe link.

I think we need to make this explicit in the documentation and probably also write a knowledgebase article on this.

The settings are under email settings, and unless you configure these to be on, even if you set a preference centre for the email which is correctly configured and includes all of the different options, it will still go to the unsubscribe link.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Language in the Absolute links section needs to be changed to english

On the Contributing to the Mautic documentation page, the language in the Absolute links section needs to be changed to English.

Bounce : important information missing

For bounce detection, mautic uses Return-path to detect wich message originated the bounce. For example, if you send an email from [email protected], mautic will insert a Return-path: [email protected]

So if your mailbox isn't configured to accept ALL email with +bounce... the mailbox will never be able to receive the bounce. And, of course, the detection will not work

So you HAVE TO activate this option with your mailbox if you want receive bounces with email sent from mautic (and it's not a standard option...)

There is no mention in the documentation

ContactId customfield {id} is not in docs

There is not any evidence in docs, that custom filed {id}, like {contactfield=id}, can be used as well.

Please add it to all necessary places like https://docs.mautic.org/en/setup/variables and so on..

Update reference to Mautic 2.x location in permissions reset codeblock

Here we are using the old Mautic 2.x locations for cache and logs which could be confusing.

Suggest that we update to Mautic 3.x directory paths and add an info block at the top of the page (using >>>) to alert folk of the difference and provide the Mautic 2.x paths.

add information about customisation of columns in contact list view

mautic/mautic#7511

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Show "added through API" event log to timeline

Mautic 3.1 adds a new event to the lead timeline: "added through API". This means that when a user was created using Mautic's API, it will be shown in the UI. The PRs that add this functionality are mautic/mautic#7538 and mautic/mautic#9067

I'm not sure if the docs have something about the lead event log (timeline), but it might be useful to end this to the end user docs.

Missing mautic:import command for importing contact in background

Warning background import requires to run php /path/to/mautic/app/console mautic:import command periodically. Add it to your cron tab.

https://docs.mautic.org/en/contacts/import-contacts

Fix links in campaign events page

/en/campaigns/campaign%20events

Improve grammar on Progressive Profiling page

In reviewing a PR I noticed that the grammar for the progressive profiling page is pretty poor. It would be a good one to update as this is a tricky area which people can often be confused by.

Incomplete documentation on campaign events

This page is somewhat missing of other events such as clicks etc. Parking here as an issue to remind me to come back to it: https://mautic.org/docs/en/campaigns/campaign_events.html

missing bi-directional zoho documentation

Hello @virlatinus you have linked the doc in your PR mautic/mautic#4068 but the doc is the old one concerning uni-directionnal sync.
Could you make the doc please ?

Thanks a lot,

N.

move companies file out of contact sections to create its own section

In mautic menu, companies is separated to contacts, but in the documentation it is a submenu of contacts. As far as mautic/mautic#8936 adds new feature, i think we should take it out of contact category

Social login doc is missing

Hello @mqueme, there is no doc about mautic/mautic#1552, could you please help ?
Thanks :)

N.

Separate out Twilio docs into plugin config and usage

When I was following the documentation for setting up Twilio, I noticed that we have everything under how to configure text messages, and nothing showing under plugins where I would expect to find information about how to configure the plugin itself.

I feel that we should separate this page out and include this part as a separate page under Plugins in the menu structure explaining how to configure the plugin, linking to it in the information about sending text messages.

Only show edit link when the user is logged in with the correct groups

I think we need to do this in /user/plugins/admin-power-tools/admin-power-tools.php by adding a check for the two groups which have edit access (Docs Team or Docs Contributors).

wrong styling of codeblocks at https://docs.mautic.org/en/home/contributing

BUG

Hello,
something appears to go wrong with the markdown to html conversion of the codeblocks parts of the contributing page.
When visiting the contributing page the links in the table of contents do not work and upon visiting the sections in firefox 80.0 (Mac OSX 10.14.2) one does not see the arrows indicating that this would be collapsible parts, while chrome (85.0.4183.83) shows them but also is unable to render the markdown as can be seen in the attached screenshot.

Behavior in firefox:

additionally, this is also not working at the very bottom of the page for markdown syntax

additionally - it would be great if mautic would have an issue template so that new users know which information to put into a new issue. Is this already planned, can I contribute somewhere to the template?

consider automating contributors/authors

Automate adding contributors to AUTHORS.md

@allcontributors have a bot to Recognize All Contributors - Including those that don't push code

https://allcontributors.org/

Bot Configuration

{
  "files": ["AUTHORS.md"],
  "imageSize": 100,
  "contributorsPerLine": 7,
  "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)",
  "contributorTemplate": "<%= avatarBlock %><br /><%= contributions %>",
  "types": {
    "custom": {
      "symbol": "🦄",
      "description": "Forum contributions.",
      "link": "[<%= symbol %>](<%= url %> \"<%= description %>\"),"
    }
  },
  "skipCi": "true",
  "contributors": []
}

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Added report column: Date added to company

mautic/mautic#8209 introduces a new report column called "Date added to company". Not sure if this needs to be mentioned in the docs somewhere, just creating this issue for visibility.

Update links in Channels overview page

/en/channels

Implement Vale as a linter for Mautic docs

Many Mautic contributors draft documentation without the knowledge of the Mautic documentation style and terminology guidelines. For many contributors, English is not the first language which makes contribution difficult and results in an inconsistent documentation.

We do not have dedicate writers to write or review contributions. To address this issue, we want to implement the Vale linter.

About Vale

Vale linter is an extension system/plugin that you can use in your git repo to enforce a standard editorial style guide that checks for syntax, grammar, and terminology when contributing to the documentation for Mautic. Vale is open-source and doesn't require installation of any programming language. It's a command-line tool and there's a desktop version for it as well. For CI purposes, it's best to use the command-line version. Many open-source organizations like Linode and GitLabs have successfully implemented Vale Linter and are happy about the results.

Steps to implement Vale in the Mautic doc repo

• Create a solid style guide for Mautic (that includes all style, grammar, terminology checks that we want Vale to perform on any doc contributions). This will serve as the blue print.

• Feed this style guide into Vale using YAML. Vale already comes with a set of styles that are implemented by default as soon you start using Vale in your git repo. These styles can be found here - https://github.com/errata-ai/vale/tree/v2/styles. In addition to the default style checks, we will need to add our own style checks based on the style guide for Mautic. Custom styles can be implemented as YAML configuration files.

• Once we get an initial set of styles in place, we must setup a CI job that executes against each new Pull Request. The result is that every pull request we will run a check for Vale rules along with other existing checks. Issues will be flagged either as warnings or errors. We can switch a rule from warning to error by editing the configuration file. The check will only mark a PR as failing if there's something objectively wrong (that is if the rule is categorized as an error). The contributors will need to fix the errors to submit the PR .

Resources

git hub repo for vale - https://github.com/errata-ai/
Documentation for Vale: https://errata-ai.gitbook.io/vale/
How Vale fits into the CI cycle- https://github.com/marketplace/actions/vale-linter

missing doc - record UTM tags - from form action

mautic/mautic#1739
@mqueme you can help ?

The page for Upgrade steps to Mautic 3 has several TODOs in the text

We need to replace the TODOs on https://docs.mautic.org/en/mautic-3-upgrade/upgrade-steps with some actual documentation 🙂

Another app/console reference

Just came across this - a good one for a newcomer so 🙇‍♀️ please leave if you are already contributing 🙇‍♀️ :)

https://contribute.mautic.org/contributing-to-mautic/developer/local-environment-setup#development-environment. There is a reference here to app/console that needs changing!

Add info about Date Files List filters

Hi,

Would it be possible to add to the page:
Those information:

---

For the date format fields, it is possible to filter with the following values

• last month
• next month
• this month
• today
• tomorrow
• yesterday
• last week
• next week
• this week
• last year
• next year
• this year

complete Text Messages settings

To make it work, it must be:

• +XXXXXXX format for the contact phone number including the + and no space.
• fulfilled in the mobile contact field.
• the configuration tab must contain the phone number with same format: +XXXXXXX
• the SID must be the one of the account, not the one of the phone number
• STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT - will stop customers from receiving messages from that particular Twilio number.

Cron jobs page is missing commands

I noticed when I was referring to the Cron jobs page to find the appropriate command for importing contacts or companies that this was missing from the page.

It would be a really good idea to compare what we have against the great forum post here and add those that are missing.

Add info about scheduled sending of reports

With this PR we introduced the ability to schedule reports to be sent by email but this is missing in the docs.

• Add to reports documentation
• Check the Cron command (mautic:reports:scheduler) is on the crons docs and specifically highlighted on the reports page as being needed for scheduled reports

https://docs.mautic.org/en/reports

Documentation translation - how and where to pull

Hi! We got polish translation of Mautic documentation, and we would like to contribute this way. How and where can we push this? Contributing notes are not covering this. It would be nice if someone can change language @ https://docs.mautic.org

New ownerfield tokens

mautic/mautic#8373 introduces new ownerfield tokens. This needs end-user documentation.

Please look at the original issue to understand the problem the user was having, and which part of the docs are affected. Thanks in advance!

No contact batch endpoint information

We have an undocumented Lead endpoint API that is public and tested

1. PUT /api/contacts/batch/edit - https://developer.mautic.org/#edit-contact
2. POST /api/contacts/batch/new - https://developer.mautic.org/#create-contact

Cache & logs now has a new location in Mautic 3.x

I noticed that we missed updating that the cache. and logs are now in /var/cache and /var/logs respectively from Mautic 3.x onwards.

We should do a search/replace to update, and add the info block at the top of the page where it is used heavily telling folk about the change in Mautic 3.x and what to use in Mautic 2.x (e.g. troubleshooting) using the markdown >>>

Update all your cron job and replace app/console with bin/console

Update the https://docs.mautic.org/en/setup/cron-jobs page and replace all app/console instances with bin/console.

focus animate unfinished sentence

In https://github.com/mautic/documentation/blob/master/en/focus/README.md there is an item:
"Animate? - simply determine if"

"if" what?

The snetence needs finishing by someone who knows what it does.

Amazon S3 Plugin poorly documented

There's no documentation on how to set up AWS S3 Plugin, what does it do, and how to test it. I got it to work but there's no way to set the region. It will take US-EAST-1 by default.

outlook plugin - differences between 2 different docs

There are some differences in these 2 docs.

In this one, it says in requirements > outlook 2013 or 2016
Also it says it is needed a the Outlook Add-in
https://www.mautic.org/docs/en/plugins/outlook.html

In the other one, it says only Outlook 2016 is required. Also, the outlook add-in must be only for windows
https://mautic.com/help/use-microsoft-outlook-plugin/

Add an 'emergency actions' documentation resource

We all make mistakes sometimes, and it would be helpful to have an emergency actions documentation resource to help people:

• Disable cron jobs
• Turn off email sending
• Clear out email queue
• Remove any pending triggers which haven't been acted upon yet
• Any other emergency actions that might be necessary

Parking this here as a reminder!

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.