diff --git a/.github/styles/Mautic/FeatureList.yml b/.github/styles/Mautic/FeatureList.yml index a83f4872..a0c65bd1 100644 --- a/.github/styles/Mautic/FeatureList.yml +++ b/.github/styles/Mautic/FeatureList.yml @@ -45,8 +45,8 @@ swap: point actions: Point Actions point triggers: Point Triggers points: Points - group: Group - groups: Groups + point group: Point Group + point groups: Point Groups plugin: Plugin plugins: Plugins report: Report diff --git a/.github/styles/Vocab/Mautic/accept.txt b/.github/styles/Vocab/Mautic/accept.txt index f4c7168b..c22c80fd 100644 --- a/.github/styles/Vocab/Mautic/accept.txt +++ b/.github/styles/Vocab/Mautic/accept.txt @@ -6,6 +6,7 @@ Autoloader autoloader Autowired autowired +Azure bcc Beanstalkd Bing @@ -18,6 +19,7 @@ CCPA Citrix Clearbit CloudAMQP +CMS config Company(ies) Composer @@ -26,6 +28,7 @@ ConnectWise Contribution(s) CORS cPanel +CRM cron Cron CTRL @@ -34,6 +37,7 @@ DDEV Do Not Contact DNC Dripflow +DSN Dynamic Web Content FALSE Focus Item @@ -42,6 +46,7 @@ Froala Froogaloop FTP gcm +GDPR GIF GitBook GitHub @@ -55,9 +60,11 @@ HTML http https HubSpot +iContact IDP IIS IMAP +IPs infographics JavaScript Joomla @@ -65,6 +72,7 @@ Joomla! Libre Licensor LinkedIn +MailChimp Mailjet Marketing Messages Mautic @@ -72,6 +80,8 @@ MaxMind Middlewares middlewares MJML +MQL +MQLs Multiselect multiselect MVP @@ -94,6 +104,7 @@ post PUT Rackspace Remarketing +REST Salesforce SAML Schimpf @@ -111,6 +122,7 @@ sublicense SugarCRM Suhosin Symfony +TLS Todo Transifex TRUE diff --git a/docs/authentication/authentication.rst b/docs/authentication/authentication.rst index fd48f39d..93a88589 100644 --- a/docs/authentication/authentication.rst +++ b/docs/authentication/authentication.rst @@ -48,8 +48,8 @@ The IDP may ask for the following settings: #. Custom attributes - Mautic requires three custom attributes in the IDP responses for the User Email, first name and last name. Username is also supported but is optional. Configure the attribute names used by the IDP in Mautic's Configuration > User/Authentication Settings under the 'Enter the names of the attributes the configured IDP uses for the following Mautic User fields' section. -Example: Azure SAML SSO -======================= +Example - Azure SAML SSO +======================== 1) Register new Enterprise applications by navigating to ``Create your own Application`` and then ``Integrate any other application you don't find in the gallery (Non-gallery)`` 2) Go to Single Sign-On diff --git a/docs/builders/creating_themes.rst b/docs/builders/creating_themes.rst index adfb731e..00cd768f 100644 --- a/docs/builders/creating_themes.rst +++ b/docs/builders/creating_themes.rst @@ -1,10 +1,6 @@ -.. vale off - Creating Themes ############### -.. vale on - :xref:`MJML` allows marketers to create and maintain beautiful and responsive Themes for Mautic easily. .. vale off @@ -127,11 +123,11 @@ File structure Steps to save the Theme package =============================== -Once your design in MJML is finalized, go through the following steps to create the Theme package: +Once you have finalized your design in MJML, go through the following steps to create the Theme package: * Save your images in the Assets folder. -* Save your MJML in the ``html`` folder as ``email.mjml.twig`` AND ``email.html.twig``. +* Save your MJML in the ``html`` folder as ``email.mjml.twig`` **and** ``email.html.twig``. * Use the ``base.html.twig`` and ``message.html.twig`` files from the basic Theme or make your changes there. @@ -139,4 +135,4 @@ Once your design in MJML is finalized, go through the following steps to create * Create a thumbnail - use the dimensions of 400px wide, 600px high. -* Compress the contents of the folder as a Zip file - ensure that the files and folders aren't within a sub-folder in the Zip file. \ No newline at end of file +* Compress the contents of the folder as a Zip file - ensure that the files and folders aren't within a sub-folder in the Zip file. diff --git a/docs/campaigns/campaign_builder.rst b/docs/campaigns/campaign_builder.rst index ce629ed3..fa97c7f3 100644 --- a/docs/campaigns/campaign_builder.rst +++ b/docs/campaigns/campaign_builder.rst @@ -198,16 +198,16 @@ Here are the different conditions that Mautic offers in the Campaign Builder: * - **Contact device** - Checks if the Contact has interacted with your Campaign from a specific device type, brand, or OS. * - **Contact field value** - - Checks if the information matches the selected criteria on the Contact record, the Contact’s primary Company, or UTM tags. + - Checks if the information matches the selected criteria on the Contact record, the Contact's primary Company, or UTM tags. * - **Contact owner** - Checks if the selected User is the Contact's owner. * - **Contact Segments** - Checks if the Contact is a member of selected Segments. * - **Contact Tags** - Checks if specified Tags are on the Contact record. - * - **Contact points** + * - **Contact Points** - Checks if the Contact has a certain number of Points or a Group score. - * - **Form field value** + * - **Form Field value** - Checks if values submitted for a selected field on a selected Form matches specified criteria. * - **Has active notification** - Checks if the Contact has an active web notification. diff --git a/docs/campaigns/creating_campaigns.rst b/docs/campaigns/creating_campaigns.rst index 1d36a24a..f9121209 100644 --- a/docs/campaigns/creating_campaigns.rst +++ b/docs/campaigns/creating_campaigns.rst @@ -19,10 +19,10 @@ following set up: #. Create a Contact Segment or a Form to initialize your Campaign. If you already have an existing Segment or Form to use, ensure that they're up-to-date. -#. Create any custom field that you need for your Contact profile. +#. Create any Custom Field that you need for your Contact profile. #. Set up and configure any Integration that you intend to use in your Campaign. -#. Set up appropriate Channels such as Text Messages, Email, Focus items to communicate with your Contacts. -#. Create Assets, Landing pages, or other Components that you want to use for your Campaign. If using Assets, ensure that you upload them before creating your Campaign. +#. Set up appropriate Channels such as Text Messages, Email, Focus Items to communicate with your Contacts. +#. Create Assets, Landing Pages, or other Components that you want to use for your Campaign. If using Assets, ensure that you upload them before creating your Campaign. Although you can set up Channels and create Components during the process of creating the Campaign, it's ideal to have them ready beforehand as it makes the Campaign building process faster and more efficient. diff --git a/docs/categories/categories-overview.rst b/docs/categories/categories-overview.rst index 4c4a32eb..4f570a59 100644 --- a/docs/categories/categories-overview.rst +++ b/docs/categories/categories-overview.rst @@ -32,11 +32,11 @@ Using Categories for Contacts .. vale on -In addition to organizing various Mautic elements Categories can be used to 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 :width: 600 :alt: Screenshot of assigning Category to Contact -Contact Categories can be used in Segment and dynamic content filters. +Mautic allows the assignment of Contact Categories in Segment and Dynamic Content filters. diff --git a/docs/channels/emails.rst b/docs/channels/emails.rst index d1f33b1e..fd9cc8c8 100644 --- a/docs/channels/emails.rst +++ b/docs/channels/emails.rst @@ -19,7 +19,7 @@ Template Emails .. vale on -Template Emails are transactional by default. They're used in Campaigns, Form submit actions, Point triggers, etc. It's possible to send template Emails to the same Contact multiple times. You can't send template Emails to a Contact outside of another Mautic Component except when sending an Email directly to a Contact - in this case Mautic clones the content. +Template Emails are transactional by default. They're used in Campaigns, Form submit actions, Point Triggers, etc. It's possible to send template Emails to the same Contact multiple times. You can't send template Emails to a Contact outside of another Mautic Component except when sending an Email directly to a Contact - in this case Mautic clones the content. .. note:: For this reason, template Emails sent directly to a Contact aren't associated with the template Email itself and thus stats aren't tracked against it. @@ -222,113 +222,6 @@ Using the Email signature Marketers can place the signature into an Email using the ``{signature}`` token. -Email delivery -############## - -As Mautic uses the :xref:`Symfony Mailer` library since v5, it supports all Symfony Mailer core plugins out of the box. Transports for other Email services might be found on GitHub or Packagist. - -SMTP transport -************** - -The SMTP transport is the default transport used for sending Emails with Mautic. It's configured in the Mautic configuration under the Email Settings tab. The configuration is the same as in the :xref:`Symfony Mailer` documentation. - -Mautic now uses a specific way of providing the connection details for Email transports to interpret, which is called a Data Source Name, or DSN. This is the example Data Source Name configuration mentioned in the :xref:`Symfony Mailer` documentation for SMTP: - -.. code-block:: shell - - smtp://user:pass@smtp.example.com:port - -Mautic creates this automatically from the values entered in the Email configuration: - -.. image:: images/emails/smtp-dsn.png - :width: 400 - :alt: SMTP API DSN example - -.. list-table:: Example DSN ``smtp://user:pass@smtp.example.com:port/path?option1=value1&option2=value2`` explained - :widths: 10 20 150 - :header-rows: 1 - :stub-columns: 1 - - * - DSN part - - Example - - Explanation - * - Scheme - - smtp - - Defines which email transport (plugin) will handle the email sending. It also defines which other DSN parts must be present. - * - User - - john - - Some transport wants username and password to authenticate the connection. Some public or private key. Some just API key. - * - Password - - pa$$word - - As mentioned above, read documentation for your particular transport and fill in the fields that are required. For SMPT this is for password. - * - Host - - smtp.mydomain.com - - For SMTP this is the domain name where your SMTP server is running. Other transports may have the domain handled inside it so many wants to put just ``default`` text here. - * - Path - - any/path - - This is usually empty. For SMTP this may be the path to the SMTP server. For other transports this may be the path to the API endpoint. - * - Port - - 465 - - Important for SMTP. The port value defines which encryption is used. This is usually 465 for SSL or 587 for TLS. Avoid using port 25 for security reasons. For other transports this may be the port to the API endpoint. - * - Options - - timeout=10 - - This is optional. This may be the timeout for the connection or similar configuration. The config form will allow you to create multiple options. - -.. note:: - Use the Mautic's global configuration to paste in the DSN information, especially the API keys and passwords. The values must be URL-encoded, and the configuration form does that for you. If you are pasting DSN settings directly into the config/local.php file, you must URL-encode the values yourself. - - -.. vale off - -Example API transport installation - -.. vale on - -********************************** -.. warning:: - Installing Symfony Transports is possible when you've :doc:`installed Mautic via Composer `. - -If you want to use :xref:`Sendgrid` API instead of SMTP to send Emails, for example, you can install the official Symfony Sendgrid Transport by running the following command that is mentioned along others in the :xref:`Symfony Mailer` documentation. - -.. code-block:: shell - - composer require symfony/sendgrid-mailer - -After that, you can configure the transport in the Mautic configuration. The example DSN is again mentioned in the :xref:`Symfony Mailer` documentation along with other transports. In the example of using the Sendgrid API, the DSN looks like this: - -.. code-block:: shell - - sendgrid+api://KEY@default - -This is how it would be set up in Mautic's Email configuration: - - .. image:: images/emails/sendgrid-api-dsn.png - :width: 400 - :alt: Sendgrid API DSN example - -To replace the Sendgrid API key, add it to the relevant field in the Email configuration and save. Mautic now uses the Sendgrid API to send Emails. - -.. warning:: - It's a nice perk that Mautic can use any transport provided by Symfony Mailer. However, be aware that such transports (from Symfony) don't support batch sending, even via API. They only send one email per request, as opposed to a thousand emails per request as is the case with some Mautic transports, which can make them slow at scale. They also don't support transport callback handling used for bounce management. If you plan to send larger volumes of Emails or need to use features which require callback handling, please consider using Email transports built specifically for such use. These plugins are available in the :doc:`Mautic Marketplace `. - -The system can either send Emails immediately or queue them for processing in batches by a :doc:`cron job `. - -Immediate delivery -****************** - -This is the default means of delivery. As soon as an action in Mautic triggers an Email to send, it's sent immediately. If you expect to send a large number of Emails, you should use the queue. Sending Email immediately may slow the response time of Mautic if using a remote mail service, since Mautic has to establish a connection with that service before sending the mail. Also attempting to send large batches of Emails at once may hit your server's resource limits or Email sending limits if on a shared host. - -Queued delivery -*************** - -Mautic works most effectively with high send volumes if you use the queued delivery method. Mautic stores the Email in the configured spool directory until the execution of the command to process the queue. Set up a :doc:`cron job ` at the desired interval to run the command: - -.. code-block:: shell - - php /path/to/mautic/bin/console messenger:consume email_transport - -Some hosts may have limits on the number of Emails sent during a specified time frame and/or limit the execution time of a script. If that's the case for you, or if you just want to moderate batch processing, you can configure batch numbers and time limits in Mautic's Configuration. See the :doc:`cron job documentation ` for more specifics. - .. vale off Tracking Opened Emails @@ -418,7 +311,7 @@ If you select an Unsubscribe folder, Mautic also appends the Email as part of th 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. +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 diff --git a/docs/channels/focus_items.rst b/docs/channels/focus_items.rst index 64e64d24..54648637 100644 --- a/docs/channels/focus_items.rst +++ b/docs/channels/focus_items.rst @@ -1,7 +1,7 @@ Focus Items ########### -Focus items allow you to engage Users on your site through bars, modals, notifications, popups, and light boxes. It's possible to initiate Focus Items at different times and with different actions such as exit intent. +Focus Items allow you to engage Users on your site through bars, modals, notifications, popups, and light boxes. It's possible to initiate Focus Items at different times and with different actions such as exit intent. You can find Focus Items listed under the Channels menu. @@ -93,7 +93,7 @@ Visitors can choose to close this type of Focus Item with the *X* button in the Full page ~~~~~~~~~ -The full page Focus Item completely takes over the whole page, hiding the rest of the page content until the visitor clicks the *X* button in the top right hand corner of the Focus Item. +The full page Focus Item completely takes over the whole page, hiding the page content until the visitor clicks the *X* button in the top right hand corner of the Focus Item. There are no additional configuration options for this style of Focus Item. @@ -127,7 +127,7 @@ This editor mode allows a simplified experience with a few fields - depending on - **Select the Form to insert** - This option is only available for Collect Data Focus Item types. It allows you to select an existing Mautic Form to use with the Focus Item. For styling and formatting reasons, you may want to create a Form specifically for the Focus Item, adding styling attributes to the Attributes tab on the Form fields. - **Link text** - This option is only available for Emphasize a Link Focus Item types. It allows you to specify the text used on the Focus Item's button. - **Link URL** - This option is only available for Emphasize a Link Focus Item types. It allows you to specify the URL where you'd like to drive visitors with the Focus Item. -- **Open in a new window** - This option is only available for Emphasize a Link Focus Item types. If set to Yes, this ensures that the link is opened in a new window. If set to No, the link opens in the current tab. +- **Open in a new window** - This option is only available for Emphasize a Link Focus Item types. If set to Yes, this ensures that the link opens in a new window. If set to No, the link opens in the current tab. Editor ~~~~~~ @@ -167,7 +167,7 @@ When creating a new Focus Item, you can set the following fields: .. vale on -**Google Analytics UTM tags** - Mautic supports UTM tagging in Emails, Focus Items, and Landing Pages. Any UTM tags with values populated are automatically appended to the end of any links used in the focus item. See :doc:`/channels/utm_tags` for more information. +**Google Analytics UTM tags** - Mautic supports UTM tagging in Emails, Focus Items, and Landing Pages. Any UTM tags with values populated are automatically appended to the end of any links used in the Focus Item. See :doc:`/channels/utm_tags` for more information. .. image:: images/focus_items/focus_item_create.png :width: 400 @@ -180,7 +180,7 @@ Using the Focus Item builder .. vale on -After you specify the general information for the Focus Item, click the builder option in the top right corner. If you've specified a URL in the Website field on the details page, the system displays a preview. If you don't see a preview, the website might block iframe previews. Hence, you may need to add the focus item to a development or staging environment without these security restrictions - if available - to see the preview. +After you specify the general information for the Focus Item, click the builder option in the top right corner. If you've specified a URL in the Website field on the details page, the system displays a preview. If you don't see a preview, the website might block iframe previews. Hence, you may need to add the Focus Item to a development or staging environment without these security restrictions - if available - to see the preview. .. note:: The preview of the website doesn't appear until you select a style from the options on the Focus Item Builder. @@ -203,11 +203,11 @@ Once you have created your Focus Item, you're ready to publish it to your websit Deploying to a website ====================== -When you save the Focus Item, the code snippet required to display it on your website is shown in a green box on the Focus Item overview. +When you save the Focus Item, Mautic shows the code snippet required to display it on your website in a green box on the Focus Item overview. .. image:: images/focus_items/focus_item_embed.png :width: 400 - :alt: Screenshot showing the Focus Item code to be embedded within a website. + :alt: Screenshot showing the Focus Item code to embed within a website. .. note:: You may need assistance from your web development team to implement the Focus Item tracking code on your website. @@ -233,6 +233,6 @@ Measuring success When using the Emphasize a Link type, Mautic displays the link on the Focus Item overview where you can view the number of unique clicks. -If you change the link in a Focus Item after deployment, all links are listed in the overview. +If you change the link in a Focus Item after deployment, Mautic lists all links in the overview. Additionally, Mautic applies UTM tags on Focus Items to both Form submissions and link clicks. If you are using a Focus Item to submit a Form, it's recommended that you have a Submit Action on the Form to record the UTM tags. \ No newline at end of file diff --git a/docs/channels/marketing_messages.rst b/docs/channels/marketing_messages.rst index 90adf48e..93c7f4bc 100644 --- a/docs/channels/marketing_messages.rst +++ b/docs/channels/marketing_messages.rst @@ -6,7 +6,7 @@ What are Marketing Messages? Located under the Channels section in Mautic, Marketing Messages is one of the Channels available to you through which you can optimize and personalize communication with your customers. -Marketing messages allow you to empower the customer to decide how they prefer to receive the content you send, by setting the Channel they prefer. +Marketing Messages allow you to empower the customer to decide how they prefer to receive the content you send, by setting the Channel they prefer. .. image:: images/marketing_messages/marketing-messages.png :width: 200 diff --git a/docs/channels/push_notifications.rst b/docs/channels/push_notifications.rst index ef27b1fe..4fcbdc7f 100644 --- a/docs/channels/push_notifications.rst +++ b/docs/channels/push_notifications.rst @@ -1,7 +1,7 @@ Mobile push notifications ########################### -Mobile notifications integrate your iOS and Android app with :xref:`OneSignal`. Using your own OneSignal account, you can now push a notification to your Contacts's mobile device - with their permission. Enable the Plugin in Mautic's Plugin manager to see Mobile Notifications listed under Channels in the menu. +Mobile notifications integrate your iOS and Android app with :xref:`OneSignal`. Using your own OneSignal account, you can now push a notification to your Contact's mobile device - with their permission. Enable the Plugin in Mautic's Plugin manager to see Mobile Notifications listed under Channels in the menu. For more detailed information see the :xref:`OneSignal iOS` and :xref:`OneSignal Android` documentation. diff --git a/docs/channels/sms.rst b/docs/channels/sms.rst index 197b7899..ed45b415 100644 --- a/docs/channels/sms.rst +++ b/docs/channels/sms.rst @@ -1,4 +1,4 @@ -SMS Text messages +SMS Text Messages ################# With the SMS Channel it's possible to send text messages from Campaigns in Mautic. @@ -22,7 +22,7 @@ Template Text Messages .. vale on -A template Text Message is automatically sent by Campaigns, Forms, Point triggers etc. You can edit Template Text Messages after creation, but they can't manually send them to a Contact list. +A template Text Message is automatically sent by Campaigns, Forms, Point Triggers etc. You can edit Template Text Messages after creation, but they can't manually send them to a Contact list. .. vale off diff --git a/docs/channels/social_monitoring.rst b/docs/channels/social_monitoring.rst index 177e5370..54417724 100644 --- a/docs/channels/social_monitoring.rst +++ b/docs/channels/social_monitoring.rst @@ -10,7 +10,7 @@ It's possible to add Contacts to Mautic through monitoring Twitter for mentions Requirements ************ -- The :doc:`/plugins/twitter` plugin must be configured +- You must first configure the :doc:`/plugins/twitter` Plugin - You must trigger the Social Monitoring :doc:`cron job ` periodically. .. vale off @@ -42,7 +42,7 @@ When selecting the Twitter Mention monitoring method, the following fields are a There are also the standard Mautic fields available: -**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors will not collect new Contacts. +**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors won't collect new Contacts. .. vale off diff --git a/docs/channels/utm_tags.rst b/docs/channels/utm_tags.rst index 990d1440..d95c056d 100644 --- a/docs/channels/utm_tags.rst +++ b/docs/channels/utm_tags.rst @@ -17,7 +17,7 @@ Using UTM tags in Mautic To use UTM tags with Google Analytics where they appear in your Google Analytics Dashboard, you must install your Google Analytics tracking code on the resource you are linking to. This synchronizes with your Google Analytics Dashboard and records the UTM tags. -If you use a Mautic landing page, you must go to Settings > Configuration > Tracking Settings, and add your Google Analytics ID. +If you use a Mautic Landing Page, you must go to Settings > Configuration > Tracking Settings, and add your Google Analytics ID. .. image:: images/utm_tags/add_ga_code.png :width: 400 @@ -40,18 +40,18 @@ The following table lists the Google Analytics UTM tags: * - Campaign Source - The referring source of the web activity. It indicates the social network, search engine, newsletter name, or any other specific source driving the traffic. * Examples: ``facebook``, ``twitter``, ``blog``, ``newsletters`` - * UTM code: utm_source + * UTM code: ``utm_source`` * Sample code: ``utm_source=facebook`` * - Campaign Medium - UTM tags - Mautic Documentation * Examples: ``cpc``, ``organic_social`` - * UTM code: utm_medium - * Sample code: utm_medium=paid_social + * UTM code: ``utm_medium`` + * Sample code: ``utm_medium=paid_social`` * - Campaign Name - The specific promotion or Campaign title that you want to track. - * Examples: summer_sale, free_trial - * UTM code: utm_campaign - * Sample code: utm_campaign=summer_sale + * Examples: ``summer_sale``, ``free_trial`` + * UTM code: ``utm_campaign`` + * Sample code: ``utm_campaign=summer_sale`` * - Campaign Content - The Assets within the messages. This non-configurable value auto-populates with the content Asset identifier associated with the specific Asset. * - Campaign Term @@ -86,7 +86,7 @@ Using UTM tags in Focus Items Mautic supports UTM tagging in :doc:`/channels/focus_items`. Mautic can automatically append UTM tags to all links in a Focus Item by entering the appropriate values in the field provided. #. Click Channels > Focus Items -#. Create a new focus item or open an existing one. +#. Create a new Focus Item or open an existing one. #. Locate the Google Analytics UTM tags section on the bottom right. #. Enter the appropriate information in the fields. #. Click Apply. \ No newline at end of file diff --git a/docs/channels/web_notifications.rst b/docs/channels/web_notifications.rst index 40232b98..8c977013 100644 --- a/docs/channels/web_notifications.rst +++ b/docs/channels/web_notifications.rst @@ -3,7 +3,7 @@ Web notifications Web Notifications can be an extremely powerful tool for the marketer. Mautic integrated with :xref:`OneSignal` which allows you to push information to a Contact as they browse through web resources (Mautic Landing Pages, or with some configuration (see :xref:`OneSignal web push`), on your own website), giving you one more Channel that you can use to build a relationship with them. -Web notifications in Mautic use OneSignal by default. Using your own OneSignal account, you can now push a notification to your Contacts's browser - with their permission. Enable the OneSignal Plugin in Mautic's Configuration to see Web Notifications listed under Channels in the menu. +Web notifications in Mautic use OneSignal by default. Using your own OneSignal account, you can now push a notification to your Contact's browser - with their permission. Enable the OneSignal Plugin in Mautic's Configuration to see Web Notifications listed under Channels in the menu. For more information see the OneSignal :xref:`OneSignal web push quickstart` documentation. diff --git a/docs/companies/companies_overview.rst b/docs/companies/companies_overview.rst index 786269f4..73515e22 100644 --- a/docs/companies/companies_overview.rst +++ b/docs/companies/companies_overview.rst @@ -24,7 +24,7 @@ You can find a table with the list of the assigned Contacts displaying the date Company duplicates ******************* -The Company name field is a unique identifier by default. You can choose any other Company field as unique identifier in the **custom fields** section. +The Company name field is a unique identifier by default. You can choose any other Company field as unique identifier in the **Custom Fields** section. In *Configuration > Company Settings* you can choose the operator used when merging Companies with multiple identifiers - either **AND** or **OR**. @@ -63,7 +63,7 @@ By default, a set of fields exist for Companies, but you can customize these fie #. Change the dropdown select box from Contact to Company objects -#. Save the custom field +#. Save the Custom Field .. vale off @@ -138,10 +138,10 @@ Through a Form When identifying a Contact through a Form, you can also associate an existing Company or create a new one if: -- The Form includes Company name as a Form field - mandatory for Company matching/creation, -- The Form includes City as a Form field - mandatory for Company matching/creation), -- The Form includes Country as a form field - mandatory for Company matching/creation, -- The Form includes State as a form field - optional for Company matching/creation. +- The Form includes Company name as a Form Field - mandatory for Company matching/creation, +- The Form includes City as a Form Field - mandatory for Company matching/creation, +- The Form includes Country as a Form Field - mandatory for Company matching/creation, +- The Form includes State as a Form Field - optional for Company matching/creation. Company scoring ================ diff --git a/docs/components/assets.rst b/docs/components/assets.rst index 719e898a..56691901 100644 --- a/docs/components/assets.rst +++ b/docs/components/assets.rst @@ -35,8 +35,13 @@ Navigate to Components > Assets. Mautic lists any Assets you have previously cre You create Assets by uploading local resources on your computer, or by locating the Asset from a remote storage host such as Amazon S3. There are limitations by size due to the settings of your server - any such restriction may display as a warning message in the file upload section. -Add UTM to Asset -~~~~~~~~~~~~~~~~~~ +.. vale off + +Add UTM codes to Asset +~~~~~~~~~~~~~~~~~~~~~~ + +.. vale on + UTM parameters appended to the download link means that UTM data is available in the resource download Report. .. code-block:: php @@ -82,7 +87,7 @@ The following fields are available: .. vale on -- **Block search engines from indexing this file** - If you don't want to index files like PDF, DOCx and so forth, setting this switch to Yes sends the X-Robots-Tag no-index http header. If set to No, the header isn't sent and your files could become indexed by search engines. +- **Block search engines from indexing this file** - If you don't want to index files like ``PDF``, ``DOCx`` and so forth, setting this switch to Yes sends the ``X-Robots-Tag no-index`` HTTP header. If set to No, the header isn't sent and your files could become indexed by search engines. Depending on the type of file uploaded, a preview may display after the upload completes. @@ -108,7 +113,7 @@ Viewing an Asset Once you've uploaded an Asset, you'll want to make it available for your Contacts to access it. Using the Download URL from the Asset section in Mautic, you can track which Contacts are downloading or viewing the Assets. -Copy and paste the link into your website, on a landing page, or as a link in an Email. +Copy and paste the link into your website, on a Landing Page, or as a link in an Email. .. note:: In a Mautic Email or Landing Page, append ``?stream=1`` to the end of the URL to open the Asset in a new tab. diff --git a/docs/components/dynamic_web_content.rst b/docs/components/dynamic_web_content.rst index e80552fc..4307b08c 100644 --- a/docs/components/dynamic_web_content.rst +++ b/docs/components/dynamic_web_content.rst @@ -107,11 +107,11 @@ Campaign-based Dynamic Web Content Creating the request ==================== -Use a Campaign Decision for ``Request Dynamic Content`` to use Campaign-based dynamic content. The Campaign Decision checks if a Campaign member visits a page where a Dynamic Content slot is. Visitors to a page with a Dynamic Content slot receive the Dynamic Content. +Use a Campaign Decision for ``Request Dynamic Content`` to use Campaign-based Dynamic Content. The Campaign Decision checks if a Campaign member visits a page where a Dynamic Content slot is. Visitors to a page with a Dynamic Content slot receive the Dynamic Content. The following fields are available: -- **Name** - the Campaign event. Start the name with something like Req-DWC: so when you're looking at Campaign Reports, you can see the event type. +- **Name** - the Campaign event. Start the name with something like ``Req-DWC``: so when you're looking at Campaign Reports, you can see the event type. - **Requested Slot Name** - Mautic checks for the slot name. You can see how many Contacts got to the Campaign event where you're checking if their visits request the slot. diff --git a/docs/components/forms.rst b/docs/components/forms.rst index 153c1877..8d472376 100644 --- a/docs/components/forms.rst +++ b/docs/components/forms.rst @@ -38,7 +38,7 @@ The following fields are available: - **Kiosk mode** - If Yes, Mautic turns off tracking of Contacts created through the Form, so that the Form doesn't generate cookies or associate any IP address with the Contact record. Marketers may refer to this as 'data entry mode'. It's ideal for using at conferences or events where several Contacts may enter their information using the same device, as it prevents associating the activity on the device to Contacts. -- **Render style** - If Yes, the Form displays with the styling from either the selected Mautic Theme or the Attributes tab of the Form fields. When No, the Form adopts the styling of where it's embedded. +- **Render style** - If Yes, the Form displays with the styling from either the selected Mautic Theme or the Attributes tab of the Form Fields. When No, the Form adopts the styling of where it's embedded. - **Theme** - Select a Mautic Theme which has styling for a Form. This dictates the styling of the Form when added to an external website or Application if 'Render style' is Yes. @@ -142,7 +142,7 @@ Based on the field selected, Mautic displays various tabs in the fields editor i General ~~~~~~~ -- **Label** - This is the title of your field, telling the visitor what you'd like them to enter in the field. The label shows before the Form field by default. +- **Label** - This is the title of your field, telling the visitor what you'd like them to enter in the field. The label shows before the Form Field by default. - **Show label?** - When No, Mautic won't display the label on the Form. @@ -152,14 +152,14 @@ General - **Help message** - This allows the marketer to add information for the visitor about what they should enter in the field, or why they should provide the information. -- **Input placeholder** - This allows the marketer to add text within the Form field, which gives the visitor an idea of what they should enter. The text disappears as soon as they click into the field, whereas default values don't. This can be particularly helpful in prompting the visitor if you require the data in a particular format, for example ``@Twitter`` for a Twitter account, including the ``@`` symbol. +- **Input placeholder** - This allows the marketer to add text within the Form Field, which gives the visitor an idea of what they should enter. The text disappears as soon as they click into the field, whereas default values don't. This can be particularly helpful in prompting the visitor if you require the data in a particular format, for example ``@Twitter`` for a Twitter account, including the ``@`` symbol. Mapped field ~~~~~~~~~~~~ The mapped field tab allows the marketer to connect a field with an existing Contact or Company field in Mautic. This allows the data from the Form submission to automatically populate into the mapped field. Without the mapping, this information won't save in the Contact profile. -The data type for the Form field should match the data type of the mapped field. For example, a date/time field should map to a Contact or Company field which uses the date/time field. +The data type for the Form Field should match the data type of the mapped field. For example, a date/time field should map to a Contact or Company field which uses the date/time field. Validation ~~~~~~~~~~ @@ -199,11 +199,11 @@ Checkbox group, radio group and select .. image:: images/forms/checkbox_field_values.png :width: 600 - :alt: Screenshot showing checkbox field values with a mapped custom field + :alt: Screenshot showing checkbox field values with a mapped Custom Field With the checkbox, radio box and select fields, the properties tab allows you to choose what should be available for the visitor to select. -If you have mapped the Form field to a Custom Field in Mautic, there is also the option to use the values provided in the Custom Field rather than listing them separately. This helps to prevent duplication and errors in the Form options. +If you have mapped the Form Field to a Custom Field in Mautic, there is also the option to use the values provided in the Custom Field rather than listing them separately. This helps to prevent duplication and errors in the Form options. If you prefer to create your own field options, the ``Optionlist`` allows you to add options with a label and value pair. @@ -244,8 +244,8 @@ Attributes - **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Manual Copy function to manually add the Form to your website or app. - **Label attributes**: this field changes the way the label text appears. You should use the format ``style="attribute: descriptor"`` to change the style. For example, to change the label to red, use ``style="color: red"`` or ``style="color: #ff0000"``. -- **Input attributes**: changes the way any text inside the Form field appears. This applies to the input placeholder text, text entered by the visitor submitting the Form, and the options for the select fields when Allow Multiple is Yes - including List - Country. -- **Field container attributes**: this changes the Form field. Use this to change the size of the box, fill color, rounded edges, or any other properties of the actual field. +- **Input attributes**: changes the way any text inside the Form Field appears. This applies to the input placeholder text, text entered by the visitor submitting the Form, and the options for the select fields when Allow Multiple is Yes - including List - Country. +- **Field container attributes**: this changes the Form Field. Use this to change the size of the box, fill color, rounded edges, or any other properties of the actual field. - **Radio/Check box label attributes**: similar to input attributes, when available this field allows you to customize the way that radio buttons and checkboxes appear. Behavior @@ -304,7 +304,7 @@ Typically you would use a Form action to populate static Segments - Segments whi :width: 600 :alt: Screenshot showing the modify Contact's Tags Form action. -- **Record UTM Tags**: if the Page your Form is on has UTM tags, whether it's a Mautic Landing Page or an external website, Mautic can record those UTM Tags and save them to the Contact record for reporting. This is useful if you want to run Reports on where your new Contacts and Form submissions are originating from. +- **Record UTM Tags**: if the page your Form is on has UTM tags, whether it's a Mautic Landing Page or an external website, Mautic can record those UTM Tags and save them to the Contact record for reporting. This is useful if you want to run Reports on where your new Contacts and Form submissions are originating from. .. image:: images/forms/record_utm_tags.png :width: 600 @@ -449,7 +449,7 @@ Creating Custom Fields .. vale on -Using an example of wanting to show specific types of car based on the manufacturer, you would create the following custom fields: +Using an example of wanting to show specific types of car based on the manufacturer, you would create the following Custom Fields: - **Car manufacturer**: this field should be of the Select data type. In this example, the options for this field are Ford, Nissan, Peugeot, and Fiat. - **Ford cars**: this field should be of the Select - Multiple data type. In this example, the available options for this field are Focus, Mustang, Fiesta, and Galaxy. @@ -466,7 +466,7 @@ Once you have created the required Custom Fields, add the parent field to the Fo :width: 600 :alt: Screenshot showing the parent field for a conditional field on a Mautic Form -If you have defined the values in the Custom Field, turn the first switch to Yes to use those values. Otherwise, create the labels and values in the Properties tab. You can also associate the Form field with a Contact field where appropriate. +If you have defined the values in the Custom Field, turn the first switch to Yes to use those values. Otherwise, create the labels and values in the Properties tab. You can also associate the Form Field with a Contact field where appropriate. .. image:: images/forms/conditional_fields_2.png :width: 600 diff --git a/docs/components/landing_pages.rst b/docs/components/landing_pages.rst index 801e05b6..75f9a6f9 100644 --- a/docs/components/landing_pages.rst +++ b/docs/components/landing_pages.rst @@ -1,8 +1,8 @@ -.. vale off - Landing Pages ############# +.. vale off + Customizing the Preference Center ********************************* diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index 5ef819cf..7f1ee1dd 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -20,10 +20,10 @@ General settings To brand that Landing Page, create a Mautic Landing Page that you'd want to greet any Contacts who visit your root ``URL``. Once you've done that, Users can sign in into Mautic by visiting ``mautic.example.com/s/login``. -* **404 page** - Select the Landing Page that you want to use as the 404 Landing Page. If you don't want to use Mautic's default 404 error page, create a custom Landing Page and select that page here. If you don't select any page, Mautic uses the default error page. +* **404 page** - Select the Landing Page that you want to use as the 404 Landing Page. If you don't want to use Mautic's default 404 error page, create a custom Landing Page and select that Landing Page here. If you don't select any page, Mautic uses the default error page. -* **Path to the cache, log, and images directory** - These are the file system paths where the cache, logs, and images are saved. +* **Path to the cache, log, and images directory** - These are the file system paths where Mautic saves the cache, logs, and images. System defaults =============== @@ -34,9 +34,9 @@ System defaults * **Default item limit per page** - The number of Contacts, Campaigns, Emails, etc. which display on each page when you go to an item section. The default is ``10``. -* **Default timezone** - The User's default time zone, typically set to the time zone of the Company headquarters. Time zones are set for individual Users. The default is ``UTC``. +* **Default timezone** - The User's default time zone, typically set to the time zone of the Company headquarters. Mautic allows the User to set their own time zones via their profile. The default is ``UTC``. - For example: headquarters is in Boston and the default is set to ``US`` Eastern Time ``America/New York``. A User in San Francisco US Pacific Time may set ``America/Los Angeles`` to use Pacific Time in the User interface. + For example: headquarters is in Boston and Mautic's timezone is ``America/New York``. A User in San Francisco which is Pacific Time may set ``America/Los Angeles`` to use Pacific Time in the User interface. * **Default language** - The initial language assigned to Users. Individual Users may select their own settings. Mautic uses ``English - United States`` by default. @@ -44,20 +44,20 @@ System defaults * **Date Range Filter Default** - Sets the default for how far back from the current date Mautic looks for data in Reports including Campaign and Email snapshots charts on the item page. This setting allows you to control the default for how far back from the current date Mautic looks for data. If you've changed the setting on a Report, Mautic uses what you've entered. Mautic's default value is ``1 Month``. -* **Default format for full dates, date only, short dates, and time only** - The default setting uses the standard US time format. The letters in the boxes are PHP code. See the :xref:`PHP manual for date functions`. +* **Default format for full dates, date only, short dates, and time only** - The default setting uses the standard American time format. The letters in the boxes are PHP code. See the :xref:`PHP manual for date functions`. CORS settings ============= -Cross-Origin Resource Sharing (CORS) enables data to pass between your website and Mautic. +Cross-Origin Resource Sharing - CORS - allows data to pass between your website and Mautic. .. image:: images/cors-settings.png :width: 600 :alt: Screenshot showing CORS Settings Configuration in Mautic -* **Restrict Domains** - When set to No, any web page can pass information to Mautic. Select Yes to limit communication with your Mautic instance to websites listed in Valid Domains strongly recommended. +* **Restrict Domains** - When set to No, any website can pass information to Mautic. Selecting ``Yes`` to limit communication with your Mautic instance to websites listed in Valid Domains is **strongly recommended**. -* **Valid Domains** - A list of domains allowed to communicate with your Mautic instance. In the text box, list the exact URL of the top level domain you want to allow, one per line. For example: ``http://www.example.com`` tracks any activity on non-secure example.com pages, but ``https://www.example.com`` won't because this is only tracking on a secure (``https://``) website. +* **Valid Domains** - A list of domains allowed to communicate with your Mautic instance. In the text box, list the exact URL of the top level domain you want to allow, one per line. For example: ``http://www.example.com`` tracks any activity on non-secure example.com pages, but ``https://www.example.com`` won't because this is only tracking on a secure ``https://`` website. .. note:: @@ -72,25 +72,25 @@ Miscellaneous settings * **Trusted hosts** - To explicitly allow the hosts that can send requests to Mautic. You can use regular expression and separate multiple hosts with a comma. i.e ``.*\.?example.com$``. If left empty, Mautic will respond to all hosts. -* **Trusted proxies** - To configure the IP addresses that should be trusted as proxies. This setting is mandatory when using Mautic behind an SSL terminating proxy. Separate multiple IP addresses by a comma. i.e ``127.0.0.1, 10.0.0.0/8, fc00::/7`` +* **Trusted proxies** - To configure the IP addresses that Mautic should trust as proxies. This setting is mandatory when using Mautic behind an SSL terminating proxy. Separate multiple IP addresses by a comma. i.e ``127.0.0.1, 10.0.0.0/8, fc00::/7`` -* **IP lookup service** - By default, Mautic uses :xref:`MaxMind's` database to identify the city of a website visitor, based on the location of the Internet Service Provider (ISP) for their IP address. +* **IP lookup service** - By default, Mautic uses :xref:`MaxMind's` database to identify the city of a website visitor, based on the location of the Internet Service Provider - ISP - for their IP address. * **IP lookup service authentication** - To use any IP lookup service which requires authentication, enter your credentials. -* **List of IPs not to track Contacts with** - To turn off tracking for particular IP addresses, enter the addresses, one per line. Mautic doesn't recommend adding your office IP address. If you list your internal IP address, Mautic won't track clicks, page hits, etc., from that IP, **including when you are testing functionality**. +* **List of IPs not to track Contacts with** - To turn off tracking for particular IP addresses, enter the addresses, one per line. Mautic doesn't recommend adding your office IP address. If you list your internal IP address, Mautic won't track clicks, page hits, etc., from that IP, **including when you are testing** which can cause difficulties. -* **List of known Bots** - Mautic has the feature to identify and turn-off tracking for several known bots. To track activity from those bots, remove them from this list. To turn off tracking for other bots, add them here (one per line). +* **List of known Bots** - Mautic has the feature to identify and turn-off tracking for several known bots. To track activity from those bots, remove them from this list. To turn off tracking for other bots, add them here - one per line. * **URL Shortener** - If you use a URL shortening service like bit.ly for links in SMS messages, enter your access token here. .. note:: - For bit.ly, use the following URL structure: https://api-ssl.bitly.com/v3/shorten?access_token=[ACCESS_TOKEN]&format=txt&longUrl + For bit.ly, use the following URL structure: ``https://api-ssl.bitly.com/v3/shorten?access_token=[ACCESS_TOKEN]&format=txt&longUrl`` * **Item max lock time** - When a User edits a Campaign, Email, Landing Page, etc., Mautic locks the item to prevent simultaneous edits by other Users. When the initial User saves and closes or cancels out, the item may remain locked for this period of time. The default is ``0 seconds``. -* **Translate page titles** - To translate page titles in the Contact activity history from non-Latin (non-English) characters to Latin characters (English). +* **Translate page titles** - To translate page titles in the Contact activity history from non-Latin characters to Latin - English - characters. Update settings @@ -102,7 +102,7 @@ Update settings * **Set the minimum stability level required for updates** - This allows you to receive notifications for early access releases. Always read the release notes before updating to an early access release. Set the minimum stability level required for updates. -* **Update Mautic through Composer [BETA]** - Set to 'Yes' if you update Mautic through Composer. This is a prerequisite if you want to install and update Plugins through the Marketplace. This becomes the default installation and update method in Mautic 5. +* **Update Mautic through Composer [beta]** - Set to 'Yes' if you update Mautic through Composer. This is a prerequisite if you want to install and update Plugins through the Marketplace. This becomes the default installation and update method in Mautic 5. Theme settings ************** @@ -126,7 +126,7 @@ Full API documentation is available :xref:`Mautic developer API`. * **Enable http basic auth?** - Enables basic authentication for Mautic's API. It's recommended to only use this with secure sites (https). -* **Access token lifetime** - When authorizing a new app or Integration, this setting limits how long the access token is valid (in minutes). The default is ``60`` minutes. +* **Access token lifetime** - When authorizing a new app or Integration, this setting limits how long the access token is valid - in minutes. The default is ``60`` minutes. For example - You add a new Integration to your SaaS platform. Enter 30 here to limit the access token validity to ``30`` minutes. If you haven't completed the authentication in that period of time, you must revalidate. @@ -154,9 +154,9 @@ Campaign settings * **Wait time before retrying a failed action** - If for any reason a Campaign action doesn't execute, this is the length of time Mautic waits before trying again. -* **Use date range for all views** - When viewing a Campaign, the date range of actions, conditions, decisions, and Contacts displayed in the tabs is based on this setting. +* **Use date range for all views** - When viewing a Campaign, the date range of actions, conditions, decisions, and Contacts displayed in the tabs, Mautic uses this date range by default. -* **Use summary statistics** - Improves performance when viewing a Campaign with thousands of events per day by using summarized data. When you first turn on this setting you will need to run a :ref:`cron job` to summarize existing data. +* **Use summary statistics** - Improves performance when viewing a Campaign with thousands of events per day by using summarized data. When you first turn on this setting you need to run a :ref:`cron job` to summarize existing data. Email settings ************** @@ -164,7 +164,7 @@ Email settings Email transport settings ======================== -As Mautic uses the :xref:`Symfony Mailer` library since v5, it supports all Symfony Mailer core plugins out of the box. Transports for other Email services might be found on GitHub or Packagist. +As Mautic uses the :xref:`Symfony Mailer` library since v5, it supports all Symfony Mailer core Plugins out of the box. SMTP transport -------------- @@ -192,29 +192,29 @@ Mautic creates this automatically from the values entered in the Email configura - Example - Explanation * - Scheme - - smtp - - Defines which email transport (plugin) will handle the email sending. It also defines which other DSN parts must be present. + - ``smtp`` + - Defines which transport Plugin handles the Email sending. It also defines which other DSN parts must be present. * - User - - john + - ``john`` - Some transport wants username and password to authenticate the connection. Some public or private key. Some just API key. * - Password - - pa$$word - - As mentioned above, read documentation for your particular transport and fill in the fields that are required. For SMPT this is for password. + - ``pa$$word`` + - As mentioned previously, read the documentation for your particular transport and fill in the fields it requires. For SMTP enter the password in this field. * - Host - - smtp.mydomain.com - - For SMTP this is the domain name where your SMTP server is running. Other transports may have the domain handled inside it so many wants to put just ``default`` text here. + - ``smtp.mydomain.com`` + - For SMTP, this is the domain name where your SMTP server is running. Other transports may have the domain handled within the Plugin, so they may instruct you to enter ``default`` here. * - Path - - any/path - - This is usually empty. For SMTP this may be the path to the SMTP server. For other transports this may be the path to the API endpoint. + - ``example/path`` + - This is usually empty. For SMTP this may be the path to the SMTP server. For other transports this may be the path to the API endpoint. Enter according to the documentation for your transport. * - Port - - 465 - - Important for SMTP. The port value defines which encryption is used. This is usually 465 for SSL or 587 for TLS. Avoid using port 25 for security reasons. For other transports this may be the port to the API endpoint. + - ``465`` + - Important for SMTP. The port value defines the encryption used. This is usually ``465`` for SSL or ``587`` for TLS. Avoid using port 25 for security reasons. For other transports this may be the port to the API endpoint. * - Options - - timeout=10 - - This is optional. This may be the timeout for the connection or similar configuration. The config form will allow you to create multiple options. + - ``timeout=10`` + - This is optional. This may be the timeout for the connection or similar configuration. The configuration allows you to create multiple options. .. note:: - Use the Mautic's global configuration to paste in the DSN information, especially the API keys and passwords. The values must be URL-encoded, and the configuration form does that for you. If you are pasting DSN settings directly into the config/local.php file, you must URL-encode the values yourself. + Use Mautic's global configuration to paste in the DSN information, especially the API keys and passwords. The values must be URL-encoded, and the configuration form does that for you. If you are pasting DSN settings directly into the ``config/local.php`` file, you must URL-encode the values yourself. .. vale off @@ -227,30 +227,47 @@ Example API transport installation .. warning:: Installing Symfony Transports is possible when you've :doc:`installed Mautic via Composer `. -If you want to use :xref:`Sendgrid` API instead of SMTP to send Emails, for example, you can install the official Symfony Sendgrid Transport by running the following command that is mentioned along others in the :xref:`Symfony Mailer` documentation. +If you want to use :xref:`SendGrid` API instead of SMTP to send Emails, for example, you can install the official Symfony SendGrid Transport by running the following command mentioned alongside others in the :xref:`Symfony Mailer` documentation. .. code-block:: shell composer require symfony/sendgrid-mailer -After that, you can configure the transport in the Mautic configuration. The example DSN is again mentioned in the :xref:`Symfony Mailer` documentation along with other transports. In the example of using the Sendgrid API, the DSN looks like this: +After that, you can configure the transport in the Mautic configuration. The example DSN is again mentioned in the :xref:`Symfony Mailer` documentation along with other transports. In the example of using the SendGrid API, the DSN looks like this: .. code-block:: shell sendgrid+api://KEY@default -This is how it would be set up in Mautic's Email configuration: +This is how you would configure Mautic's Email configuration: .. image:: images/sendgrid-api-dsn.png :width: 400 - :alt: Sendgrid API DSN example + :alt: SendGrid API DSN example To replace the SendGrid API key, add it to the relevant field in the Email configuration and save. Mautic now uses the SendGrid API to send Emails. .. warning:: - It's a nice perk that Mautic can use any transport provided by Symfony Mailer. However, be aware that such transports (from Symfony) don't support batch sending, even via API. They only send one email per request, as opposed to a thousand emails per request as is the case with some Mautic transports, which can make them slow at scale. They also don't support transport callback handling used for bounce management. If you plan to send larger volumes of Emails or need to use features which require callback handling, please consider using Email transports built specifically for such use. These plugins are available in the :doc:`Mautic Marketplace `. + It's a nice perk that Mautic can use any transport provided by Symfony Mailer. However, be aware that such transports from Symfony **don't support batch sending, even via API**. They only send one Email per request, as opposed to a thousand Emails per request as is the case with some Mautic transports, which can make them slow at scale. They also **don't support transport callback handling used for bounce management**. If you plan to send larger volumes of Emails or need to use features which require callback handling, please consider using Email transports built specifically for such use. These Plugins are available in the :doc:`Mautic Marketplace `. -The system can either send Emails immediately or queue them for processing in batches by a :doc:`cron job `. +The table below lists available transport Plugins created for Mautic to include support for batch sending and callback handling. + +.. vale off + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Link to Packagist + - Command for installing + * - :xref:`sparkpost-transport` + - ``composer require ts-navghane/sparkpost-plugin`` +.. vale on + +Queue settings +============== + +The system can either send Emails immediately or queue them for processing in batches by a :doc:`cron job `. Documentation relating to configuring the queue is in the :doc:`queue ` section. Immediate delivery ------------------ @@ -263,8 +280,8 @@ Queued delivery Mautic works most effectively with high send volumes if you use the queued delivery method. Mautic stores the Email in the configured spool directory until the execution of the command to process the queue. Set up a :doc:`cron job ` at the desired interval to run the command: .. code-block:: shell - - php /path/to/mautic/bin/console messenger:consume email_transport + + php /path/to/mautic/bin/console messenger:consume email Some hosts may have limits on the number of Emails sent during a specified time frame and/or limit the execution time of a script. If that's the case for you, or if you just want to moderate batch processing, you can configure batch numbers and time limits in Mautic's Configuration. See the :doc:`cron job documentation ` for more specifics. @@ -284,7 +301,7 @@ Mail send settings Ensure that you configure your sender domain, ``DKIM``, bounce, and click tracking domains. For more information, see the :ref:`Email` documentation. -* **Reply to address** - To have Contacts reply to a different address than the specified From address, add the desired address here. This is the default ``reply-to`` address where messages are sent from Mautic unless it is overridden in an individual Email. If this field is blank, the address specified in **Email address to send mail** from is used. The ``reply-to`` setting is useful if your configured sender domain - which you use in the from address - contains a subdomain that doesn't have MX records or is otherwise an address that can't receive Emails. +* **Reply to address** - To have Contacts reply to a different address than the specified From address, add the desired address here. This is the default ``reply-to`` address where messages are sent from Mautic unless it is overridden in an individual Email. If this field is blank, Mautic uses the address specified in **Email address to send mail from**. The ``reply-to`` setting is useful if your configured sender domain - which you use in the from address - contains a subdomain that doesn't have MX records or is otherwise an address that can't receive Emails. * **Custom return path (bounce) address** - Set a custom return path/bounce Email address for Emails sent from the system. Note that some mail transports, such as GMail, won't support this. @@ -302,14 +319,8 @@ See :ref:`here` to set the Contact's Em Default frequency rule ====================== - -.. vale off - * **Do not contact more than each ** - This limits the number of Marketing Messages a Contact receives in a certain period of time day, week, month. Transactional messages don't count towards this limit. You can adjust this at the individual Contact level, either manually or by Preference Center setting. -.. vale on - - .. note:: More information is available in the :doc:`Default Frequency Rule documentation`. @@ -600,9 +611,13 @@ If a Campaign or Webhook is automatically unpublished because of a high volume o * **Send notification to author** - Set this field to Yes to send an Email notification to the User who created the unpublished Campaign or Webhook. Deleted Users don't receive notifications. -Landing page settings +.. vale off + +Landing Page settings ********************* +.. vale on + .. image:: images/landing-page-settings.png :width: 600 :alt: Screenshot showing Landing Page Settings Configuration in Mautic @@ -638,7 +653,7 @@ Mautic tracking settings .. note:: * The tracking code automatically detects the Preferred Timezone and Preferred Locale fields. - * Landing Pages including 4-byte UTF-8 characters, such as emojis and some Chinese or other non-Latin characters, in the Landing Page title or URL aren't tracked on a Contact's activity history in Mautic. All Latin characters used in English and other western languages are of 1-byte and are tracked. + * Landing Pages including 4-byte UTF-8 characters, such as emojis and some Chinese or other non-Latin characters, in the Landing Page title or URL aren't tracked on a Contact's activity history in Mautic. Mautic tracks all Latin characters used in English and other western languages which are of 1-byte. Facebook pixel ============== @@ -649,9 +664,9 @@ Facebook pixel * **Facebook Pixel ID** - Enter your Facebook Pixel ID and select the options you'd like to use the pixel for. -* **Enabled on your tracking landing page** - Select Yes to have Mautic append the Facebook Pixel to the Mautic tracking code to track Landing Pages where the tracking code exists. +* **Enabled on your tracking Landing Page** - Select Yes to have Mautic append the Facebook Pixel to the Mautic tracking code to track Landing Pages where the tracking code exists. -* **Enabled on Mautic landing page** - Select Yes to have Mautic add the Facebook Pixel to Mautic landing pages. +* **Enabled on Mautic Landing Page** - Select Yes to have Mautic add the Facebook Pixel to Mautic Landing Pages. Google analytics @@ -663,9 +678,9 @@ Google analytics * **Google Analytics ID** - Enter your Google Analytics ID and select the options you'd like to use the pixel for. -* **Enabled on your tracking landing page** - Select Yes to have Mautic append the Google Analytics script to the Mautic tracking code to track Landing Pages where the tracking code exists. +* **Enabled on your tracking Landing Page** - Select Yes to have Mautic append the Google Analytics script to the Mautic tracking code to track Landing Pages where the tracking code exists. -* **Enabled on Mautic landing page** - Select Yes to have Mautic add the Google Analytics script to Mautic landing pages. +* **Enabled on Mautic Landing Page** - Select Yes to have Mautic add the Google Analytics script to Mautic Landing Pages. * **Enabled IP** ``Anonymization`` - For subscribers sensitive to General Data Protection Regulation or other data privacy laws and regulations, select Yes to anonymize the IP address of web visitors before sending it to Google Analytics.* diff --git a/docs/contacts/contacts_overview.rst b/docs/contacts/contacts_overview.rst index 0047c22b..b26fb395 100644 --- a/docs/contacts/contacts_overview.rst +++ b/docs/contacts/contacts_overview.rst @@ -12,8 +12,8 @@ Contact types There are two types of Contacts: -Visitors (formerly anonymous leads) -=================================== +Visitors - formerly ``anonymous leads`` +======================================= Unidentified visitors to your site who haven't yet completed a Form or otherwise interacted with your site. @@ -37,7 +37,7 @@ If you have an IP lookup service :ref:`configured` in ** * Scoring -* Data from Forms - which don't include the unique identifier, since that would make the contact known +* Data from Forms - which don't include the unique identifier, since that would make the Contact known .. note:: diff --git a/docs/contacts/custom_fields.rst b/docs/contacts/custom_fields.rst index 9739a636..06d4bf98 100644 --- a/docs/contacts/custom_fields.rst +++ b/docs/contacts/custom_fields.rst @@ -35,7 +35,7 @@ You'll notice the group column shows the specific field on the Contact profile. 2. **List icon** - You can use these fields as filters for Segments. -3. **Asterisks icon** - These fields are required when filling in the Contact Form +3. **Asterisks icon** - These are mandatory when filling in the Contact Form 4. **Globe icon** - You can update these fields publicly through the :doc:`tracking pixel` URL query see :doc:`Contact Monitoring` for more details. @@ -83,7 +83,7 @@ Adding a new Custom Field .. vale on -You can create additional custom fields and define the data type you want that field to hold. In addition to the data type you select the group for that particular field. This defines where the field displays on the Contact edit and detail view. +You can create additional Custom Fields and define the data type you want that field to hold. In addition to the data type you select the group for that particular field. This defines where the field displays on the Contact edit and detail view. .. image:: images/new-custom-field.jpeg :align: center @@ -100,7 +100,7 @@ There is a way around this when you configure the processing of field creation i Since :xref:`Mautic 3` there is an option you can set in your ``app/config/local.php`` file: ``'create_custom_field_in_background' => true``,. -If you configure this option, the new Custom Field becomes visible in the list of Custom Fields. The custom field remains unpublished until you run the command ``bin/console mautic:custom-field:create-column``. This command creates the actual column in the table and publishes the field metadata. +If you configure this option, the new Custom Field becomes visible in the list of Custom Fields. The Custom Field remains unpublished until you run the command ``bin/console mautic:custom-field:create-column``. This command creates the actual column in the table and publishes the field metadata. This configuration helps prevent **http** request timeouts because it handles the long-running SQL query to create the new table column as a background task. diff --git a/docs/contacts/import_contacts.rst b/docs/contacts/import_contacts.rst index db74ad97..b44d7c1d 100644 --- a/docs/contacts/import_contacts.rst +++ b/docs/contacts/import_contacts.rst @@ -1,10 +1,6 @@ -.. vale off - Import Contacts ############### -.. vale on - Contact importing is possible through the User Interface in Mautic. For larger imports it's recommended to complete the import in the background via a cron job. Since Mautic 2.9, Mautic shows in a Contact's event history when an import job creates or updates a Contact. @@ -197,11 +193,11 @@ When the background job finishes, either successfully or if it fails, you'll get FAQ *** -Q. The import times out. +Q. The import times out, what should you do? A. Either use the background job to import, or change the batch limit to smaller number than 100. -Q: Are imported *Do Not Contact* values stored as a bounce or a ``unsubscription``? +Q. What happens with imported *Do Not Contact* values? Are they stored as a bounce or a ``unsubscription``? A. It's stored as a ``Manual Unsubscription``. It's the same as marking the Contact *Do Not Contact* from the Contact's page. diff --git a/docs/contacts/manage_contacts.rst b/docs/contacts/manage_contacts.rst index 9af04b64..ab5aa8e4 100644 --- a/docs/contacts/manage_contacts.rst +++ b/docs/contacts/manage_contacts.rst @@ -14,7 +14,7 @@ Searching for Contacts .. vale on -You can search within a Segment using the box at the top of the list, or order Contacts by using the table headings - click on the relevant table heading. +You can search within a Segment using the box at the top of the list, or order Contacts by using the table headings - click the relevant table heading. .. image:: images/contacts-search.jpeg :align: center @@ -44,9 +44,13 @@ Quick Add is a short Form with the fields you deem most important. To display fi You can add the Contact through the New Contact Form and include much more detail, but for quick entry this is the easiest and fastest way to get the Contact into the system. +.. vale off + Add new Contact =============== +.. vale on + .. image:: images/contact-manual-add.png :align: center :alt: Screenshot of Contact Manual Add @@ -111,7 +115,7 @@ When Mautic tracks a Contact's actions - such as page hits or Form submissions - * Cookie -Mautic merges all actions to the Contact with the same cookie or creates a new cookie if it knows the unique `device_id`. +Mautic merges all actions to the Contact with the same cookie or creates a new cookie if it knows the unique ``device_id``. If a Contact sends a Form with an Email address, it merges the submission with the Contact having the same Email address. This happens even if the IP address or the cookie matches another Contact. @@ -134,7 +138,7 @@ A modal window displays when you click one of the actions, with more configurati -You can use this feature to quickly update large volumes of Contacts, but it might be better to use a Campaign action - for example add all the Contacts you need to update into a segment and use a campaign to trigger the change - if you need to change more than a few hundred Contacts at a time. +You can use this feature to quickly update large volumes of Contacts, but it might be better to use a Campaign action - for example add all the Contacts you need to update into a Segment and use a Campaign to trigger the change - if you need to change more than a few hundred Contacts at a time. .. image:: images/batch-actions.png :width: 200 @@ -165,8 +169,12 @@ The following batch actions are currently available: If you need to delete large numbers of Contacts, visit the :doc:`segment docs` which explains how to delete thousands of Contacts easily. -Contact details -*************** +.. vale off + +Individual Contact details +************************** + +.. vale on Each Contact has a detail page where you can see what Mautic knows about them. @@ -178,16 +186,16 @@ The Engagements line chart display how active the Contact was in the past 6 mont Image ===== -* **Gravatar** - By default, Mautic pulls images from Gravatar. If there’s a :xref:`Gravatar` associated with the Contact’s Email address, Mautic will add the Gravatar photo to the contact record. +* **Gravatar** - By default, Mautic pulls images from Gravatar. If there's a :xref:`Gravatar` associated with the Contact's Email address, Mautic adds the Gravatar photo to the Contact record. * **Custom** - To add a custom image file to a Contact, edit the Contact record and look for **Preferred profile image** under the image placeholder. -* **Social** - If you’ve enabled social Plugins and the record includes a social profile, you’ll see options to pull in profile images. +* **Social** - If you've enabled social Plugins and the record includes a social profile, you'll see options to pull in profile images. History ======= -Event history tracks any engagements between Mautic and a Contact. To find certain event types, search in the **Include events by source** text box. To exclude event types from the history while you’re looking at it, use **Exclude events by source**. +Event history tracks any engagements between Mautic and a Contact. To find certain event types, search in the **Include events by source** text box. To exclude event types from the history while you're looking at it, use **Exclude events by source**. **Accessed from IP** - IP addresses which the Contact has opened or clicked Emails, visited your tracked pages, etc. from. @@ -197,7 +205,7 @@ Event history tracks any engagements between Mautic and a Contact. To find certa **Campaign Action Triggered** - Actions within Campaigns which have already happened. -**Campaign Event Scheduled** - Actions within Campaigns which take place in the future. Expand the details to see the event’s scheduled date and time. Click the clock icon to reschedule the event, or click **X** to cancel the event. A warning icon means an execution error on the first try caused a rescheduling of the event. +**Campaign Event Scheduled** - Actions within Campaigns which take place in the future. Expand the details to see the event's scheduled date and time. Click the clock icon to reschedule the event, or click **X** to cancel the event. A warning icon means an execution error on the first try caused a rescheduling of the event. **Campaign Membership Change** - Changes to which Campaign a Contact is a part of. @@ -213,7 +221,7 @@ Event history tracks any engagements between Mautic and a Contact. To find certa **Dynamic Content sent** - When the Contact has a Dynamic Content slot pushed to them through a Campaign action. -**Email Failed** - If an Email to the Contact reports back as the Email address being an invalid address or the Email being undeliverable, Mautic displays an Email failed event with the internal name of the Email shown. +**Email Failed** - If an Email to the Contact returns back as the Email address being an invalid address or the Email being undeliverable, Mautic displays an Email failed event with the internal name of the Email shown. **Email Read** - The date and time when a specific Email was first read. If the Contact opens the Email multiple times, expanding details on the event type displays the additional opens. @@ -231,7 +239,7 @@ Event history tracks any engagements between Mautic and a Contact. To find certa **Integration Sync Notice** - Information about connections with Integrations. -**Message Queue** - When exceeding a Contact’s frequency limits for a Channel and a message on that Channel later triggers to send, a Message Queue event displays with the Channel and the ID for the message that's queued. Expanding details displays: +**Message Queue** - When exceeding a Contact's frequency limits for a Channel and a message on that Channel later triggers to send, a Message Queue event displays with the Channel and the ID for the message that's queued. Expanding details displays: * originally scheduled send date * rescheduled send date @@ -239,7 +247,7 @@ Event history tracks any engagements between Mautic and a Contact. To find certa If the message is ``Pending``, clicking the X button cancels it. -**Page Hit** - Time and date of page visits, and the URL if it’s a tracked page on your site or the internal name of a Mautic Landing Page. You may view more information, if tracked, by expanding the details of this event type. +**Page Hit** - Time and date of page visits, and the URL if it's a tracked page on your site or the internal name of a Mautic Landing Page. You may view more information, if tracked, by expanding the details of this event type. **Point Gained** The ID number of either: @@ -253,7 +261,7 @@ If the message is ``Pending``, clicking the X button cancels it. **Text Message Received** - This event type is for SMS replies, if you are using SMS and have SMS reply tracking configured. Outbound SMS display as ``Campaign Event Scheduled`` or ``Campaign Action Triggered``. -**UTM Tags Recorded** - If you’re using UTM tags and record them from a Form submission, landing page hit, etc., Mautic displays them here. Expanding the details displays the recorded tags. +**UTM Tags Recorded** - If you're using UTM tags and record them from a Form submission, Landing Page hit, etc., Mautic displays them here. Expanding the details displays the recorded tags. **Video View Event** - Details in this event type include the length of time a prospect watched the video, the percentage of the video watched, the page where the video displays - known as Referrer - and the URL of the video file. @@ -272,7 +280,7 @@ If a Contact record includes social profiles, you can see them in the **Social** Integrations ============ -If the Contact exists in other tools has connections through Plugin or API Integrations, you’ll see those here. This helps identify where a Contact came from, or what other internal systems the Contact exists in. +If the Contact exists in other tools has connections through Plugin or API Integrations, you'll see those here. This helps identify where a Contact came from, or what other internal systems the Contact exists in. Map === @@ -370,16 +378,16 @@ Make sure you enter your website URL correctly as outlined in the :doc:`CORS set Note that if a browser doesn't accept cookies, this may result in each hit creating a new visitor. -.. code-block:: +.. code-block:: javascript - + mt('send', 'pageview'); + *Don't forget to change the scheme (http(s)) either to http or https depending what scheme you use for your Mautic. Also, change [example.com] to the domain where your Mautic runs.* @@ -393,8 +401,8 @@ The advantage of JavaScript tracking is that the tracking request - which can ta * **Page URL** the URL of the current website. -mt() events -~~~~~~~~~~~ +``mt() events`` +~~~~~~~~~~~~~~~ mt() supports two callbacks, ``onload`` and ``onerror`` accepted as the fourth argument. The ``onload`` method fires at loading of the pixel. If the pixel fails for whatever reason, it triggers ``onerror``. @@ -426,7 +434,7 @@ You can attach custom parameters or overwrite the automatically generated parame This code sends all the automatic data to Mautic and adds also ``email`` and ``firstname``. Your system must generate the values of those fields. -The tracking code also supports Company fields. Mautic can assign a Company to your tracked Contact based on Company name. Then you have to add the **company** or ``**companyname**`` parameter to the tracking code, along with other Companies fields such as ``companyemail``, ``companyaddress1``, ``companyaddress2``, ``companyphone``, ``companycity``, ``companystate``, ``companyzipcode``, ``companycountry``, ``companywebsite``, ``companynumber_of_employees``, ``companyfax``, ``companyannual_revenue``, ``companyindustry``, ``companyindustry``, ``companydescription``. +The tracking code also supports Company fields. Mautic can assign a Company to your tracked Contact based on Company name. Then you have to add the ``**company**`` or ``**companyname**`` parameter to the tracking code, along with other Companies fields such as ``companyemail``, ``companyaddress1``, ``companyaddress2``, ``companyphone``, ``companycity``, ``companystate``, ``companyzipcode``, ``companycountry``, ``companywebsite``, ``companynumber_of_employees``, ``companyfax``, ``companyannual_revenue``, ``companyindustry``, ``companyindustry``, ``companydescription``. You can also use Contact tags and UTM codes. @@ -458,7 +466,7 @@ To get the most out of the tracking pixel, it's recommended that you pass inform Page information ~~~~~~~~~~~~~~~~ -Mautic currently supports ``page_url``, ``referrer``, ``language``, and ``page_title`` - note that the use of ``url`` and ``title`` is deprecated due to conflicts with Contact fields. +Mautic currently supports ``page_url``, ``referrer``, ``language``, and ``page_title`` - note the deprecation of ``url`` and ``title`` due to conflicts with Contact fields. UTM code ~~~~~~~~ @@ -480,17 +488,17 @@ Please note that Mautic records UTM tags only on a Form submission that contains * - Values - Class * - social, ``socialmedia`` - - fa-share-alt if utm_source isn't available, otherwise Mautic uses utm_source as the class. For example, if utm_source is Twitter, the entry uses fa-twitter. - * - email, newsletter - - fa-envelope-o - * - banner, ad - - fa-bullseye + - ``fa-share-alt`` if utm_source isn't available, otherwise Mautic uses ``utm_source`` as the class. For example, if ``utm_source`` is Twitter, the entry uses ``fa-twitter``. + * - ``email``, ``newsletter`` + - ``fa-envelope-o`` + * - ``banner``, ``ad`` + - ``fa-bullseye`` * - ``cpc`` - - fa-money - * - location - - fa-map-marker + - ``fa-money`` + * - ``location`` + - ``fa-map-marker`` * - ``device`` - - fa-tablet if utm_source isn't available otherwise Mautic uses utm_source as the class. For example, if utm_source is Mobile, Mautic uses fa-mobile. + - ``fa-tablet`` if ``utm_source`` isn't available otherwise Mautic uses ``utm_source`` as the class. For example, if ``utm_source`` is ``Mobile``, Mautic uses ``fa-mobile``. All the UTM tags are available in the time entry, just by toggling the entry details button. @@ -504,7 +512,7 @@ You can also pass information specific to your Contact by setting Mautic Contact Tags ~~~~ -You can change the Contact's Tags by using the ``tags`` query parameter. Multiple Tags can be separated by comma. To remove a Tag, prefix it with a dash (minus sign). +You can change the Contact's Tags by using the ``tags`` query parameter. You can separate multiple Tags by comma. To remove a Tag, prefix it with a dash (minus sign). For example, ``mtracking.gif?tags=ProductA``,-ProductB would add the ProductA Tag to the Contact and remove ProductB. @@ -538,7 +546,7 @@ PHP JavaScript ~~~~~~~~~~ -.. code-block:: +.. code-block:: javascript