Document truly transactional emails v2 feature by promptless-for-oss · Pull Request #723 · mautic/user-documentation

promptless-for-oss · 2026-05-25T08:20:32Z

Open this suggestion in Promptless to view citations and reasoning process

Add comprehensive documentation for the new transactional email capabilities: Send to unsubscribed contacts toggle, Repeatable email campaign action setting, Disable unsubscribe link header configuration, Send to unsubscribed contacts permission, and updated frequency rules behavior. Updated permission label to match the actual UI.

Trigger Events

Tip: Use Slack message actions (⋯ menu → Update Docs) to capture doc updates without interrupting conversations 💬

adiati98

@promptless-for-oss please address the suggestions

promptless-for-oss · 2026-05-25T11:34:16Z

Thanks for the review feedback, @adiati98! I've addressed all your suggestions in commit cd84557:

✅ Wrapped the "Send to unsubscribed contacts" paragraph in vale off/on
✅ Fixed warning admonition indentation (3-space indent) and expanded acronyms on first use:
- GDPR → General Data Protection Regulation
- CAN-SPAM → Controlling the Assault of Non-Solicited Pornography And Marketing Act
- CASL → Canada's Anti-Spam Legislation
✅ Fixed note admonition indentation and wrapped in vale off/on statements
✅ Changed passive voice to active voice throughout:
- "When enabled" → "Enabling prevents..."
- "When disabled" → "Disabling causes..."
- "When is set to" → "When you set to"
✅ Changed parentheses to dashes, Gmail → GMail

adiati98

@promptless-for-oss please address the suggestions

promptless-for-oss · 2026-05-25T11:48:31Z

Thanks for the review feedback @adiati98! I've addressed all your suggestions:

Expanded acronyms: Updated the warning text to use the full names with dash format (General Data Protection Regulation - GDPR, etc.)
Changed list markers: Switched from dashes to asterisks for the unordered list
Fixed Vale warnings: Replaced "functionality" with "capability" and added "RFC" to the Vale accept.txt vocabulary file

The changes have been pushed to this PR.

escopecz · 2026-05-25T14:25:14Z

We'll need to rebase this to 7.2

promptless-for-oss · 2026-05-25T14:27:16Z

Thanks for the feedback! I checked and the 7.2 branch doesn't exist yet in this repository. The current versioned branches are: 5.2, 6.0, 7.0, and 7.1.

Once the 7.2 branch is created, I'll rebase this PR to target it. Just let me know when it's available, or I can watch for it and rebase automatically.

promptless-for-oss · 2026-05-25T14:30:41Z

I've strengthened the legal warning in the transactional emails documentation. The warning now explicitly states:

It's illegal in many countries to send marketing emails to unsubscribed contacts
This feature is intended only for genuinely transactional communications (receipts, password resets, etc.)
Misuse can result in serious legal consequences including fines

Please review the updated changes.

escopecz

Looks good. Just must be merged into the 7.2 branch

promptless-for-oss · 2026-05-25T14:31:09Z

Thank you for the approval! As noted above, the 7.2 branch doesn't exist yet. I'll rebase and retarget this PR as soon as the branch is created.

adiati98

@promptless-for-oss please address the suggestions

promptless-for-oss · 2026-05-26T11:02:54Z

I've addressed the PR review feedback from @adiati98:

Changes made (commit 1d86379):

Added .. vale off / .. vale on directives around the 4 content blocks as requested
Added CAN, CASL, and SPAM to the Vale vocabulary file (GDPR was already present)

Note: The Vale vocabulary file .github/styles/config/vocabularies/Mautic/accept.txt is outside the docs/ directory scope that Promptless can modify. The changes to that file may need to be applied manually or the scope configuration updated. The RST file changes with the Vale directives have been successfully applied.

The PR has been updated with these changes.

adiati98 · 2026-05-26T11:41:47Z

@promptless-for-oss please rebase to 7.2 branch

Add documentation for the new transactional email capabilities introduced in mautic/mautic#15995: - Document Send to unsubscribed contacts toggle in emails.rst - Update Send Email campaign action to describe Repeatable email toggle - Add Disable unsubscribe link in header setting to settings.rst - Document Include unsubscribed contacts permission in managing_roles.rst - Update frequency_rules.rst to explain interaction with the new toggle - Update default frequency rule description in settings.rst

Updated 'Include unsubscribed contacts' to 'Send to unsubscribed contacts' in emails.rst and managing_roles.rst to match the actual label shown in the Mautic UI.

- Fix RST indentation for warning and note admonitions (3-space indent) - Expand GDPR, CAN-SPAM, and CASL acronyms on first use - Wrap note admonition in vale off/on statements - Change passive voice to active voice in frequency rules behavior - Use dashes instead of parentheses in settings.rst - Change Gmail to GMail per style guide - Use active voice throughout

Changes per reviewer suggestions: - Change acronym format from parentheses to dashes (GDPR, CAN-SPAM Act, CASL) - Use asterisks instead of dashes for unordered list items - Replace 'functionality' with 'capability' in settings.rst - Add RFC to Vale accept.txt vocabulary

Address PR review feedback: add more prominent warning that sending marketing emails to unsubscribed contacts is illegal in many countries and can result in serious legal consequences including fines.

@adiati98

- Add vale off/on directives around content blocks that contain feature names and terminology that trigger Vale warnings - Add CAN, CASL, and SPAM to accept.txt vocabulary file Addresses review comments from @adiati98.

promptless-for-oss · 2026-05-26T11:43:54Z

Done! I've rebased this PR to target the 7.2 branch as requested. The branch has been rebased and the PR base has been updated.

adiati98

@promptless-for-oss please address the suggestions

@adiati98

Apply all 8 reviewer suggestions from @adiati98: - Add RST target labels for cross-referencing sections - Simplify opening text and use **bold** for UI elements - Adjust permissions wording and add :ref: cross-references - Simplify frequency rules text with proper punctuation - Use active voice and restructure Campaign action table for readability

promptless-for-oss · 2026-05-29T08:50:10Z

I've addressed all 8 suggestions from the review:

✅ Simplified the opening text with bold Advanced tab formatting
✅ Added RST target label .. _setting granular permissions: for cross-referencing
✅ Adjusted permissions wording with :ref: cross-reference to the new target
✅ Simplified frequency rules text with clearer formatting
✅ Added RST target label .. _send to unsubscribed Contacts: for the main section
✅ Changed to :ref: direct link using the new target label
✅ Rewrote Email permissions description with bold Advanced for consistency
✅ Restructured Campaign action table cell with active voice and bullet list format

Changes have been pushed to the branch. Vale linting shows no new errors from these changes.

🤖 Generated with Promptless

adiati98

@promptless-for-oss please address the suggestions

- Remove 'CAN' and 'SPAM' from accept.txt vocabulary file - Add vale off/on directives around regulation abbreviations (GDPR, CAN-SPAM, CASL) in the warning block - Rewrite frequency rules section using active voice ("When you set") instead of passive voice ("is set")

promptless-for-oss · 2026-05-29T09:10:42Z

I've addressed all the review feedback:

✅ Removed 'CAN' and 'SPAM' from .github/styles/config/vocabularies/Mautic/accept.txt
✅ Added .. vale off/on directives around the regulation abbreviation expansions (GDPR, CAN-SPAM, CASL) in the warning block
✅ Rewrote the frequency rules section using active voice ("When you set Send to unsubscribed contacts to Yes") instead of passive voice

The PR is ready for re-review.

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

adiati98

@promptless-for-oss please address the suggestions

@adiati98

Apply PR review feedback from @adiati98: - Fix image and note indentation in settings.rst (2 to 3 spaces) - Remove unnecessary vale off/on from frequency_rules section header - Move vale off before intro paragraph, vale on after Yes case - Simplify the No case text and remove bullet formatting

promptless-for-oss · 2026-05-29T09:33:56Z

Thanks for the review feedback @adiati98! I've applied all 5 suggestions:

Fixed indentation for the "Do Not Contact more than..." bullet point with properly placed vale off/on directives
Simplified the "Send to unsubscribed contacts" No case text
Removed vale off/on statements from the "Emails and frequency rules" section header
Added vale off before the frequency rules intro paragraph
Adjusted vale on placement to after the "Yes" case bullet point

The PR has been updated with these fixes. Please let me know if there's anything else that needs adjustment.

adiati98

@promptless-for-oss please address the suggestions

- settings.rst: Use specific vale rule Mautic.FeatureList = NO/YES instead of generic vale off/on for frequency rule bullet - frequency_rules.rst: Remove empty bullet point - frequency_rules.rst: Make "Send to unsubscribed contacts = No" a proper bullet and move vale on directive after it

promptless-for-oss · 2026-05-29T09:55:16Z

Thanks @adiati98! I've applied all three suggestions:

Changed .. vale off / .. vale on to .. vale Mautic.FeatureList = NO / .. vale Mautic.FeatureList = YES around the frequency rule bullet point
Removed the empty bullet point
Made "Send to unsubscribed contacts = No" a proper bullet point and moved .. vale on to appear after both frequency rule bullets

Changes pushed to the branch.

…irectives Replace `.. vale Mautic.FeatureList = NO/YES` with `.. vale off/on` for the frequency rule section as requested in PR review.

promptless-for-oss · 2026-05-29T10:15:46Z

Thanks for the suggestion — I've applied it and pushed the change.

Regarding why Vale keeps giving warnings despite the directives: Vale has known limitations with reStructuredText comment handling. According to Vale's GitHub issues tracker:

Issue docs: create new doc for mailchimp plugin app #340: Vale on/off comments do not work on titles in RST files
Issue #1028: Vale fails to respect ignore directives in RST literal blocks
Issue Merge main into 5.x branch ready for release #175 (fixed): Comments weren't honored in RST files within list contexts

The original directive used rule-specific syntax (.. vale Mautic.FeatureList = NO), which only disables that single rule. The general .. vale off directive you suggested disables all Vale checking for that section, which may have broader coverage.

However, Vale's RST parser has inconsistent behavior depending on the structural context (lists, titles, literal blocks). If warnings persist even with .. vale off, it's likely a Vale bug with RST parsing rather than incorrect syntax.

The workaround in such cases is to:

Rephrase the content to avoid triggering the rule, or
Add the specific terms to the Vale vocabulary/exception list

adiati98 · 2026-05-29T12:35:16Z

-* **Do Not Contact more than <number> each <period>** - 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 off
+
+* **Do Not Contact more than <number> each <period>** - This limits the number of Emails a Contact receives in a certain period of time: day, week, or month. Emails with **Send to unsubscribed contacts** enabled don't count towards this limit. You can adjust this at the individual Contact level, either manually or via the **Preference Center** setting.


@escopecz I have a question.

I tried this locally and I'd like to know: how to adjust Send to unsubscribed contacts at the individual level manually?

Regarding via the Preference Center setting, is it correct to set it from the "Contact Preference Center" as the screenshot below?

I think the paragraph should be reformulated. When it states:

You can adjust this

Then the this refers to:

This limits the number of Emails a Contact receives in a certain period of time: day, week, or month.

Not to

Emails with Send to unsubscribed contacts enabled don't count towards this limit.

The Send to unsubscribed contacts is configured on each email entity. Not in the preference center. Perhaps this sentence should be added at the end of the paragraph?

@escopecz

Move the "Send to unsubscribed contacts" exception to the end of the paragraph so that "You can adjust this" clearly refers to the frequency limit setting, not to the transactional email behavior. Addresses review feedback from @escopecz.

promptless-for-oss · 2026-05-29T15:22:34Z

Thanks for the feedback @escopecz! I've reordered the paragraph so "You can adjust this" now immediately follows the frequency limit sentence, with the transactional email exception moved to the end:

This limits the number of Emails a Contact receives in a certain period of time: day, week, or month. You can adjust this at the individual Contact level, either manually or via the Preference Center setting. Emails with Send to unsubscribed contacts enabled don't count towards this limit.

The change has been pushed to the branch.

adiati98

@promptless-for-oss please address the suggestions

- Fix indentation in campaign_builder.rst (8 spaces to 6 spaces) - Add clarifying sentence about configuring Send to unsubscribed contacts on Email entities - Add vale off/on around frequency rules documentation link in note block - Add vale off/on around Unsubscribe settings section

promptless-for-oss · 2026-05-29T16:13:05Z

Thanks for the review feedback @adiati98! I've addressed all your suggestions:

✅ Fixed the grammar for the "Send to unsubscribed contacts" sentence
✅ Added clarification that Send to unsubscribed contacts is configured on each Email entity, not in the Preference Center
✅ Added the .. vale off / .. vale on directives around the frequency rules documentation link
✅ Added the .. vale off before the {unsubscribe_text} token line and .. vale on after

The changes have been pushed to this branch.

adiati98 · 2026-05-29T16:19:06Z

-* **Do Not Contact more than <number> each <period>** - 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 off
+
+* **Do Not Contact more than <number> each <period>** - This limits the number of Emails a Contact receives in a certain period of time: day, week, or month. You can adjust this at the individual Contact level, either manually or via the **Preference Center** setting. Emails with **Send to unsubscribed contacts** enabled don't count towards this limit. You configure **Send to unsubscribed contacts** on each Email entity, not in the Preference Center.


@escopecz this is what Promptless came up with the update. I'm still not sure if this is correct.

Would this capture the intention? Also, I still don't understand how to adjust the limit manually in the individual Contact level and the difference with adjust it on the Contact Preference Center.

Suggested change

* **Do Not Contact more than <number> each <period>** - This limits the number of Emails a Contact receives in a certain period of time: day, week, or month. You can adjust this at the individual Contact level, either manually or via the **Preference Center** setting. Emails with **Send to unsubscribed contacts** enabled don't count towards this limit. You configure **Send to unsubscribed contacts** on each Email entity, not in the Preference Center.

* * **Do Not Contact more than <number> each <period>** - This option limits the number of Emails a Contact receives in a certain period of time: day, week, or month. You can adjust this limit at the individual Contact level, either manually or via the **Contact Preference Center** setting. Emails with **Send to unsubscribed contacts** enabled in the individual Email settings don't count towards this limit.

@promptless-for-oss don't change anything yet. Wait for reply from @escopecz.

promptless-for-oss · 2026-05-29T16:20:53Z

Thanks for flagging this @adiati98. I'll wait for @escopecz's input on whether this is accurate. If any corrections are needed based on their review, I'll update the documentation accordingly.

promptless-for-oss · 2026-05-30T08:07:05Z

Thanks for the review @adiati98! 👍 I'll hold off on making any changes until @escopecz weighs in on the frequency rules wording and the questions about:

How to adjust the limit manually at the individual Contact level
The difference between manual adjustment vs. the Contact Preference Center setting

Standing by for their input.

promptless-for-oss requested a review from a team as a code owner May 25, 2026 08:20

promptless-for-oss requested review from adiati98 and favour-chibueze and removed request for a team May 25, 2026 08:20

promptless-for-oss commented May 25, 2026

View reviewed changes

Comment thread docs/channels/emails.rst

promptless-for-oss mentioned this pull request May 25, 2026

Truly transactional emails mautic/mautic#15995

Merged

adiati98 requested changes May 25, 2026

View reviewed changes

adiati98 added this to the Mautic 7.2 milestone May 25, 2026

adiati98 requested changes May 25, 2026

View reviewed changes

Comment thread docs/channels/emails.rst Outdated

Comment thread docs/channels/emails.rst Outdated

Comment thread docs/configuration/settings.rst Outdated

adiati98 requested a review from escopecz May 25, 2026 11:45

escopecz previously approved these changes May 25, 2026

View reviewed changes

adiati98 requested changes May 26, 2026

View reviewed changes

promptless-for-oss dismissed escopecz’s stale review via 1d86379 May 26, 2026 11:02

promptless-for-oss requested review from a team and adiati98 May 26, 2026 11:02

promptless Bot added 6 commits May 26, 2026 11:43

Fix permission name to match actual UI label

5a2fef1

Updated 'Include unsubscribed contacts' to 'Send to unsubscribed contacts' in emails.rst and managing_roles.rst to match the actual label shown in the Mautic UI.

Strengthen legal warning for send to unsubscribed contacts

85bf02d

Address PR review feedback: add more prominent warning that sending marketing emails to unsubscribed contacts is illegal in many countries and can result in serious legal consequences including fines.

promptless-for-oss force-pushed the promptless/transactional-emails-v2 branch from 1d86379 to 8d94603 Compare May 26, 2026 11:43

promptless-for-oss changed the base branch from 7.1 to 7.2 May 26, 2026 11:43

adiati98 requested changes May 29, 2026

View reviewed changes

Comment thread docs/channels/emails.rst

Comment thread docs/contacts/frequency_rules.rst

Comment thread docs/contacts/frequency_rules.rst

Comment thread docs/contacts/frequency_rules.rst Outdated

Comment thread docs/contacts/frequency_rules.rst

Apply suggestions from code review

6b931c0

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

adiati98 requested changes May 29, 2026

View reviewed changes

Comment thread docs/configuration/settings.rst Outdated

Comment thread docs/contacts/frequency_rules.rst Outdated

Comment thread docs/contacts/frequency_rules.rst Outdated

Comment thread docs/contacts/frequency_rules.rst

Comment thread docs/contacts/frequency_rules.rst

adiati98 requested changes May 29, 2026

View reviewed changes

Comment thread docs/configuration/settings.rst

Comment thread docs/contacts/frequency_rules.rst Outdated

Comment thread docs/contacts/frequency_rules.rst Outdated

adiati98 reviewed May 29, 2026

View reviewed changes

Comment thread docs/configuration/settings.rst Outdated

Apply reviewer suggestion: use vale off/on instead of rule-specific d…

763948a

…irectives Replace `.. vale Mautic.FeatureList = NO/YES` with `.. vale off/on` for the frequency rule section as requested in PR review.

Merge branch '7.2' into promptless/transactional-emails-v2

98c9481

adiati98 reviewed May 29, 2026

View reviewed changes

Reorder frequency rule paragraph for clarity

911d477

Move the "Send to unsubscribed contacts" exception to the end of the paragraph so that "You can adjust this" clearly refers to the frequency limit setting, not to the transactional email behavior. Addresses review feedback from @escopecz.

adiati98 requested changes May 29, 2026

View reviewed changes

Comment thread docs/campaigns/campaign_builder.rst Outdated

Comment thread docs/configuration/settings.rst Outdated

Comment thread docs/configuration/settings.rst

Comment thread docs/configuration/settings.rst

Comment thread docs/configuration/settings.rst

adiati98 reviewed May 29, 2026

View reviewed changes

Conversation

promptless-for-oss commented May 25, 2026

Uh oh!

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented May 25, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented May 25, 2026

Uh oh!

escopecz commented May 25, 2026

Uh oh!

promptless-for-oss commented May 25, 2026

Uh oh!

promptless-for-oss commented May 25, 2026

Uh oh!

escopecz left a comment

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss commented May 25, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented May 26, 2026

Uh oh!

adiati98 commented May 26, 2026

Uh oh!

promptless-for-oss commented May 26, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented May 29, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented May 29, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!