Merge branch '5.x' into DPMMA-2688_smart-camapign-schedule

.all-contributorsrc

@@ -104,6 +104,24 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "uadf",
+      "name": "CPweb",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2785980?v=4",
+      "profile": "https://eglise.catholique.fr",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "heebinho",
+      "name": "Renato Heeb",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1469531?v=4",
+      "profile": "http://renatoheeb.com",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/styles/Mautic/FeatureList.yml

@@ -49,6 +49,8 @@ swap:
   point groups: Point Groups
   plugin: Plugin
   plugins: Plugins
+  publish: Activate or Turn On
+  published: Active or Available
   report: Report
   reports: Reports
   role: Role
@@ -59,7 +61,9 @@ swap:
   stages: Stages
   theme: Theme
   themes: Themes
+  unpublish: Deactivate or Turn Off
+  unpublished: Unavailable or Deactivated
   user: User
   users: Users
   webhook: Webhook
-  webhooks: Webhooks
+  webhooks: Webhooks

.github/workflows/linting.yml

@@ -4,18 +4,26 @@ on:
 
 jobs:
   prose:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04 # See https://github.com/errata-ai/vale-action/issues/128 before upgrading
     steps:
     - name: Checkout
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+        cache: 'pip'
+
+    - name: Install Python dependencies
+      run: pip3 install -r docs/requirements.txt
+
     - name: Vale
       uses: errata-ai/vale-action@reviewdog
       with:
         # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
-        version: 2.29.2
+        version: 3.7.1
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.gitpod.Dockerfile

@@ -1,8 +1,7 @@
 FROM python:3.11
 
-# Don't update to a higher version until this issue has been fixed: https://github.com/errata-ai/vale/issues/528
 # Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
-ENV VALE_VERSION=2.29.2
+ENV VALE_VERSION=3.7.1
 
 WORKDIR /workspace
 

.gitpod.yml

@@ -1,6 +1,5 @@
-# Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily
-# use this once which has Python 3.9 and Vale preinstalled.
-image: dennisameling/python-vale:latest
+image: 
+  file: .gitpod.Dockerfile
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -9,7 +8,7 @@ tasks:
 vscode:
   extensions:
     - ms-python.python
-    - lextudio.restructuredtext
+    - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading.
     - trond-snekvik.simple-rst
     - errata-ai.vale-server
     - eamodio.gitlens

.vscode/settings.json

@@ -5,5 +5,8 @@
     "esbonio.sphinx.buildDir": "${workspaceFolder}/build",
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
     "restructuredtext.pythonRecommendation.disabled": true,
-    "restructuredtext.preview.name": "sphinx"
+    "restructuredtext.preview.name": "sphinx",
+    "esbonio.sphinx.pythonCommand": "python3",
+    "esbonio.sphinx.buildCommand": "sphinx-build",
+    "esbonio.logging.level": "debug"
 }

.well-known/funding-manifest-urls

@@ -0,0 +1 @@
+https://github.com/mautic/mautic/blob/5.x/funding.json

README.md

@@ -1,6 +1,6 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
@@ -87,7 +87,7 @@ You can automatically build changes to rst files using a file watcher.
 [RST Cheatsheet]: <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>
 [Sphinx Template]: <https://github.com/readthedocs/sphinx_rtd_theme/tree/master/docs/demo>
 [Sphinx Demo]: <https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/structure.html>
-[Vale]: <https://docs.errata.ai/vale/install>
+[Vale]: <https://vale.sh/docs/vale-cli/installation/>
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -111,6 +111,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/J-Wick4"><img src="https://avatars.githubusercontent.com/u/1954540?v=4?s=100" width="100px;" alt="John Wick"/><br /><sub><b>John Wick</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/issues?q=author%3AJ-Wick4" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jagtapreshma"><img src="https://avatars.githubusercontent.com/u/81143250?v=4?s=100" width="100px;" alt="jagtapreshma"/><br /><sub><b>jagtapreshma</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=jagtapreshma" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/markusVJH"><img src="https://avatars.githubusercontent.com/u/121946942?v=4?s=100" width="100px;" alt="Markus Heinilä"/><br /><sub><b>Markus Heinilä</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=markusVJH" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://eglise.catholique.fr"><img src="https://avatars.githubusercontent.com/u/2785980?v=4?s=100" width="100px;" alt="CPweb"/><br /><sub><b>CPweb</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/pulls?q=is%3Apr+reviewed-by%3Auadf" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://renatoheeb.com"><img src="https://avatars.githubusercontent.com/u/1469531?v=4?s=100" width="100px;" alt="Renato Heeb"/><br /><sub><b>Renato Heeb</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=heebinho" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>

docs/campaigns/campaign_builder.rst

@@ -272,4 +272,34 @@ Actions and Decisions in Mautic require a :doc:`cron job</configuration/cron_job
 
    php /path/to/mautic/bin/console mautic:campaigns:trigger
 
-If you want to execute the command at different intervals for specific Campaigns, you can pass the ``--campaign-id=ID`` argument to the command.
+If you want to execute the command at different intervals for specific Campaigns, you can pass the ``--campaign-id=ID`` option to the command.
+
+If you want to ignore specific Campaigns, you can pass the ``--exclude=ID`` option to the command. Passing multiple options will ignore multiple Campaigns.
+
+.. vale off
+
+Cloning Campaign events
+-----------------------
+
+.. vale on
+
+Since Mautic 5.1, the Campaign builder includes a feature that allows Users to clone - copy and paste - Campaign events, making it easier to replicate complex workflows or reuse specific actions, decisions, or conditions across different Campaigns. This feature supports cloning events within the same Campaign as well as between different Campaigns.
+
+To clone an event:
+
+1. Hover over the Campaign event that you want to clone and click the copy icon button to store the event in the clipboard:
+
+.. image:: images/clone-campaign-event.png
+  :width: 277
+  :alt: Screenshot of hovering over a Campaign event to reveal the clone option
+
+
+2. Click on the anchor of the event after which you want to insert the cloned event. This opens up a modal window.
+
+3. In the modal window, click the "Insert" button to paste the stored event:
+
+.. image:: images/paste-cloned-event-modal.png
+  :width: 583
+  :alt: Screenshot of the modal window with the insert option to paste the cloned event
+
+The cloned event is now inserted in the Campaign workflow.

docs/campaigns/creating_campaigns.rst

@@ -5,7 +5,7 @@ Creating Campaigns
 
 .. vale on
 
-Creating Campaigns is a central part of the marketing automation process. When you create a new Campaign, you perform the basic administrative tasks such as choosing a name for the Campaign, creating a description, assigning a Category and defining publishing information for the Campaign.
+Creating Campaigns is a central part of the marketing automation process. When you create a new Campaign, you perform the basic administrative tasks such as choosing a name for the Campaign, creating a description, assigning a Category and defining activating information for the Campaign.
 
 At the heart of any marketing automation Campaign is the Campaign Builder. This allows you to specify how Contacts enter the Campaign, and what happens at every point after they enter the workflow.
 
@@ -51,7 +51,7 @@ To begin creating Campaigns, perform the following steps:
 
 -  **Category** - Choose a Category to assign your Campaign to. Categories help you organize your Campaigns. To learn more about creating and managing Categories, see :doc:`/categories/categories-overview`.
 -  **Allow Contacts to restart the Campaign** - Click the toggle switch to allow Contacts to restart the Campaign if you're building a Campaign for a recurring message - for example birthdays, subscriptions - or transactional operations - for example activity notifications, updating data. Enabling this option allows Contacts to go through the same Campaign multiple times.
--  **Published** - Click the toggle switch to publish or un-publish the Campaign. Ensure that you don't publish a Campaign until you're actually ready for it to go live. You can also schedule to publish or un-publish a Campaign at a future date by selecting a time and date.
+-  **Active** - Click the toggle switch to turn the Campaign on or off. Ensure that you don't activate a Campaign until you're actually ready for it to go live. You can also schedule to activate or deactivate a Campaign at a future date by selecting a time and date.
 
 #. Click **Launch Campaign Builder** to start building your Campaign, and add at least one event. For information about how to use the
    Campaign Builder, see :doc:`/campaigns/creating_campaigns`.

docs/campaigns/managing_campaigns.rst

@@ -17,7 +17,7 @@ The following image shows a sample Campaign overview with its highlighted panels
     :width: 600
     :alt: Screenshot showing the Campaign overview
 
-The **Details** drop-down menu gives a quick overview of the most important information about your Campaign. This information includes the name of the User who created the Campaign, Category of the Campaign, creation date and time, publishing date and time, Contact Segments in your Campaign and more.
+The **Details** drop-down menu gives a quick overview of the most important information about your Campaign. This information includes the name of the User who created the Campaign, Category of the Campaign, creation date and time, activating date and time, Contact Segments in your Campaign and more.
 
 The **Campaign Statistics** panel shows the number of Contacts added to the Campaign over the specified period of time in graphical format. To specify the time period, use the From and To date selectors, and click Apply.
 

docs/categories/categories-overview.rst

@@ -19,22 +19,22 @@ Creating and managing Categories
 
 To create new Categories, go to settings menu in the top right corner of Mautic. There choose Categories.
 
-.. image:: images/create-new-category.jpeg
+.. image:: images/create-new-category.png
   :width: 600
   :alt: Screenshot of create new Category
 
 .. vale off
 
-When creating a new Category you can select type, title, description, alias, color and published status. The color will be helpful to quickly find Mautic elements by their appropriate Category when viewing things like the Calendar or other areas within Mautic.
+When creating a new Category you can select type, title, description, alias, color and availability status. The color will be helpful to quickly find Mautic elements by their appropriate Category when viewing other areas within Mautic.
 
 Using Categories for Contacts
 ******************************
 
 .. vale on
 
-In addition to organizing various Mautic elements Categories can help you organize Contacts. In Contact details use the Preference menu to open Contact Preference Center.
+In addition to organizing various Mautic elements, Categories can help you organize Contacts. In Contact details use the Preference menu to open Contact Preference Center.
 
-.. image:: images/assign-category-to-contact.jpeg
+.. image:: images/assign-category-to-contact.png
   :width: 600
   :alt: Screenshot of assigning Category to Contact
 

docs/channels/emails.rst

@@ -39,6 +39,19 @@ Segment Emails are marketing Emails by default. On creation the marketer assigns
 
 This entry field is a multi-select which allows you to choose several Segments if necessary.
 
+.. vale off
+
+Excluding Segments
+==================
+
+.. vale on
+
+There is a multi-select field that allows excluding Contacts belonging given Segments.
+
+.. image:: images/emails/email-excluding-segments.png
+  :width: 400
+  :alt: Screenshot showing selecting Segments to exclude.
+
 Mautic initiates the sending of these Emails with a :doc:`/configuration/cron_jobs` - see section on Send Scheduled Broadcasts - for example, Segment Emails - for more details on this.
 
 Email formats
@@ -65,6 +78,12 @@ When creating the Email, there is an option to assign a language and a translati
 
 It's also possible to have translations of A/B test variants.
 
+From Mautic 5.1 it's possible to preview A/B and Translation variants:
+
+.. image:: images/emails/ab-translation-preview.png
+  :width: 400
+  :alt: Screenshot showing A/B and Translation preview
+
 Base64 encoded images
 =====================
 
@@ -83,10 +102,12 @@ Tokens
 
 Mautic allows the use of tokens in Emails which gives the marketer the possibility to integrate a number of Contact fields in your Emails. These can be easily placed within your Emails and are automatically replaced with the appropriate text once sent.
 
+It's also possible to override the 'from' field in an Email with a token from your :doc:`/contacts/custom_fields` since Mautic 5.1. 
+
 Check the :doc:`/configuration/variables` documentation for a list of all the available default fields.
 
 Default value
-~~~~~~~~~~~~~
+-------------
 
 A token can have a default value for cases when the Contact doesn't have the value known. You must specify the default value after a ``|`` character, for example:
 
@@ -97,7 +118,7 @@ A token can have a default value for cases when the Contact doesn't have the val
 The ``|friend`` tells Mautic to use 'friend' if there is no first name present in the Contact field.
 
 Encoded value
-~~~~~~~~~~~~~
+-------------
 
 It's possible to encode values used in a token using the following syntax:
 
@@ -108,7 +129,7 @@ It's possible to encode values used in a token using the following syntax:
 The ``|true`` tells Mautic to encode the value used, for example in URLs.
 
 Date formats
-~~~~~~~~~~~~
+------------
 
 To use custom date fields in tokens, use the following format:
 
@@ -144,7 +165,7 @@ To make use of monitoring replies from Contacts, you must have access to an IMAP
 ``php path/to/mautic/bin/console mautic:email:fetch``
 
 Usage
-~~~~~
+-----
 Contact replies within Campaigns function as decision after an Email Send action, to take further action based on whether the Contact has replied to the Email. Mautic tries to read the inbox, parse messages, and find replies from the specified Contact. The Contact, when matched with an incoming reply, proceeds down the positive path immediately after the reply detection.
 
 
@@ -242,20 +263,32 @@ Tracking links in Emails
 
 .. vale on
 
-Mautic tracks clicks of each link in an Email, with the stats displayed at the bottom of each Email detail view under the Click Counts tab.
+Mautic tracks clicks of each link in an Email, with the stats displayed at the bottom of each Email detail view under the Click Counts tab.  
+
+You can turn off tracking for a certain link by adding the ``mautic:disable:tracking="true"`` HTML attribute.  
+
+For example:
+
+.. code-block:: html
+
+  <a href="https://mautic.example.com/" mautic:disable:tracking="true">Non tracked link</a>
 
 Unsubscribing
 *************
 
-Mautic has a built in means of allowing a Contact to unsubscribe from Email communication. You can insert the tokens ``{unsubscribe_text}`` or ``{unsubscribe_url}`` into your Email to have the text or the URL show at your desired location. The unsubscribe text token inserts a sentence with a link instructing the Contact to click to unsubscribe. 
+Mautic has a built in means of allowing a Contact to unsubscribe from Email communication. You can insert various tokens into your Email to provide unsubscribe options at your desired location:
+- ``{unsubscribe_text}``: Inserts a sentence with a link instructing the Contact to click to unsubscribe.
+- ``{unsubscribe_url}``: Inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not.
+- ``{dnc_url}``: Inserts the URL to unsubscribe from all marketing messages when the preference center is activated.
 
 The unsubscribe URL token inserts the URL into your custom written instructions. 
 
 For example:
 
 .. code-block:: html
 
-        <a href="{unsubscribe_url}" target="_blank">Want to unsubscribe?</a>
+        <a href="{unsubscribe_url}" target="_blank">Manage your email preferences</a>
+        <a href="{dnc_url}" target="_blank">Unsubscribe from all emails</a>
 
 You can find the configuration of the unsubscribe text in the global settings.
 
@@ -271,7 +304,7 @@ For example:
     <a href="{webview_url}" target="_blank">View in your browser</a>
 
 Bounce management
-#################
+*****************
 
 Mautic provides a feature which allows monitoring of IMAP accounts to detect bounced Emails and unsubscribe requests.
 
@@ -284,7 +317,7 @@ Elastic Email, SparkPost, Mandrill, Mailjet, SendGrid and Amazon SES support Web
 .. vale off
 
 Monitored inbox configuration
-*****************************
+=============================
 
 .. vale on
 
@@ -309,15 +342,15 @@ If sending mail through GMail, the Return Path of the Email is automatically rew
 If you select an Unsubscribe folder, Mautic also appends the Email as part of the "List-Unsubscribe" header. It then parses messages it finds in that folder and automatically unsubscribe the Contact.
 
 Webhook bounce management
-*************************
+=========================
 
 Since Mautic 5 all the Email transports use the same Webhook - sometimes called callback - URL: ``https://mautic.example.com/mailer/callback``. Please follow the documentation for the specific Email transport you've installed to get more information about the Webhook configuration.
 
 
 .. vale off
 
 Create a Segment with bounced Emails
-************************************
+=====================================
 
 .. vale on
 
@@ -370,4 +403,3 @@ This is because Mautic sends test Emails to a Mautic User and not to a Mautic Co
 Mautic Users can't unsubscribe and therefore the unsubscribe link looks like this: ``https://mautic.example.com/|URL|``. However, the link **does** work correctly when you send the Email to a Contact.
 
 Best practice is to create a Segment with a small number of Contacts to receive test Emails - for example, yourself - which ensures that you can fully test features such as unsubscribe behaviour.
-