bench get-app https://github.com/Alex-Yablonsky/frappe-email-flow

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Alex-Yablonsky%2Ffrappe-email-flow)](https://frappegems.com/gems/apps/Alex-Yablonsky/frappe-email-flow)

Frappe Email Flow

Frappe Email Flow is a provider-neutral email queue rules, delays and delivery-flow control app for Frappe Framework.

Current release: v1.0.2

Developed and maintained by Yablonsky.io.

It helps Frappe administrators control when outgoing emails leave the standard Email Queue, without replacing SMTP, Postfix, Frappe Email Account, or any existing email delivery provider.

---

Why this app exists

Frappe has a powerful notification and email system, but real business workflows often generate several emails from the same event.

For example, one form submission or business action can trigger:

• a user confirmation email;
• an internal team notification;
• a report email;
• a PDF attachment email;
• a follow-up email;
• a system alert.

Without delivery-flow control, those emails may arrive too quickly, in the wrong order, or without enough separation between user-facing and internal messages.

This app solves that problem by adding rule-based control at the Email Queue level.

Use it when you need:

• immediate confirmation emails;
• delayed internal notifications;
• delayed report or attachment emails;
• randomised delay ranges;
• safe bypass for password reset and security emails;
• dry-run testing before production;
• audit logs showing which rule matched;
• provider-neutral email flow control;
• no external email API dependency;
• no replacement of the existing Frappe email system.

---

Main features

Email Queue flow control

Frappe Email Flow runs before a new Email Queue document is inserted.

It can apply:

• no delay;
• fixed delay;
• random delay range;
• optional priority override;
• critical email bypass;
• match logging;
• unmatched logging.

The actual sending still happens through Frappe’s normal email worker and configured outgoing email account.

Rule-based matching

Rules can match outgoing emails by:

• reference DocType;
• reference name;
• subject;
• recipient;
• sender;
• CC;
• message body;
• attachment presence.

Dry-run mode

Dry-run mode lets you test rule behaviour without changing actual email delivery timing.

When Dry Run is enabled, the app logs what would have happened but does not apply the delay.

Critical email bypass

Critical emails can bypass all delays.

This is important for:

• password reset emails;
• verification links;
• OTP / 2FA codes;
• account invitations;
• login alerts;
• security alerts;
• urgent billing or system messages.

Desk workspace and app icon

The app includes:

• a Desk workspace;
• quick links to Settings, Rules and Logs;
• a Desktop app icon for the main Desk screen.

---

Requirements

• Frappe Framework v16.
• A working Frappe bench and site.
• Configured outgoing email in Frappe.
• Access to Desk / Admin.
• Standard Frappe background workers.

No external database, SaaS backend, AI provider, or third-party delivery service is required.

---

Compatibility

Tested with

• Frappe Framework v16.18.x.
• Ubuntu-based production bench environment.
• Standard Frappe Email Queue.
• Frappe Notifications and frappe.sendmail() workflows.

ERPNext compatibility

ERPNext is not required.

The app is expected to work on ERPNext v16 sites that run on Frappe Framework v16, because it works at the Frappe email queue layer and does not depend on ERPNext-specific DocTypes.

Frappe CRM compatibility

Frappe CRM is not required.

The app can be used with Frappe CRM workflows if those workflows create outgoing emails through the standard Frappe email system.

---

How it works

Frappe Notification / sendmail / system email
        ↓
Email Queue document is created
        ↓
Frappe Email Flow before_insert hook applies rules
        ↓
Email Queue.send_after / priority / logs are set
        ↓
Standard Frappe worker sends through the existing email account

Frappe Email Flow does not send emails itself.

It only controls timing and diagnostic logging for standard Frappe Email Queue records.

---

Installation

From your Frappe bench:

bench get-app frappe_email_flow https://github.com/Alex-Yablonsky/frappe-email-flow
bench --site your-site.example.com install-app frappe_email_flow
bench --site your-site.example.com migrate
bench build --app frappe_email_flow
bench --site your-site.example.com clear-cache

Restart your web and worker processes if needed:

sudo supervisorctl restart your-bench-name-web:
sudo supervisorctl restart your-bench-name-workers:

Updating an existing local installation

If the app is already installed on the site and you are updating local code:

./env/bin/pip install -e apps/frappe_email_flow --no-deps
bench --site your-site.example.com migrate
bench build --app frappe_email_flow
bench --site your-site.example.com clear-cache
bench restart

---

Admin access

Open Desk and search for:

Email Flow Settings

Direct admin URLs usually look like:

/app/email-flow-settings

or:

/desk/email-flow-settings

The Desk workspace is available at:

/desk/email-flow

The workspace provides quick access to:

• Settings;
• Rules;
• Logs.

---

Configuration

Configure the app in Email Flow Settings.

Recommended first setup

Field	Recommended starting value	Description
Enabled	1	Turns the app on.
Dry Run	1	Logs what would happen without applying real delays.
Fail Open	1	Allows normal email sending if rule evaluation fails.
Never Delay Critical Emails	1	Protects password reset, verification and security emails.
Max Delay Seconds	3600	Safety limit for calculated delays.
Log Matches	1	Logs matched rules.
Log Unmatched	1	Logs emails where no rule matched.

Keep Dry Run enabled until the rules are confirmed in Email Flow Log.

Only disable Dry Run after test emails match the correct rules.

---

Rule actions

Each rule can choose one action.

No Delay

The email is allowed to leave the queue immediately.

Use this for:

• confirmation emails;
• urgent user-facing emails;
• messages that should always go first.

Fixed Delay

The email receives a fixed delay in seconds.

Use this when you need predictable timing.

Example:

Delay Seconds: 60

Random Delay Range

The app selects a random delay between minimum and maximum values.

Use this when you want emails to feel naturally spaced.

Example:

Min Delay Seconds: 180
Max Delay Seconds: 300

---

Rule examples with placeholders only

The examples below use placeholder marker tokens.

Do not copy them as real production values.

Rule 1 — confirmation immediately

Rule Name: Example Confirmation Immediate
Enabled: Yes
Priority: 10
Message Contains: 
Action: No Delay
Stop After Match: Yes

Rule 2 — internal notification short delay

Rule Name: Example Internal Notification Delay
Enabled: Yes
Priority: 20
Message Contains: 
Action: Random Delay Range
Min Delay Seconds: 15
Max Delay Seconds: 30
Stop After Match: Yes

Rule 3 — report delivery delay

Rule Name: Example Report Delivery Delay
Enabled: Yes
Priority: 30
Message Contains: 
Has Attachment: Yes
Action: Random Delay Range
Min Delay Seconds: 180
Max Delay Seconds: 300
Stop After Match: Yes

Expected flow:

T+0 sec: user receives confirmation.
T+15–30 sec: internal team receives notification.
T+180–300 sec: user receives the report email.

---

Marker-based matching

The recommended production-safe matching pattern is to add a unique marker to each email template body or footer.

Use visible ASCII-only markers:

ID: 

Then configure the rule to match only the token value:

Message Contains: 

Why markers are recommended

Email subjects and bodies can be changed by:

• translation;
• MIME encoding;
• template edits;
• branding changes;
• user language;
• dynamic data.

A stable marker makes matching more reliable.

Marker safety rules

Generate unique marker values per installation and preferably per email type.

Do not use:

• predictable values such as 001, 002, 003;
• public example tokens;
• readable counters;
• reused tokens from another installation;
• real customer identifiers;
• secrets;
• API keys;
• passwords;
• internal business logic names.

Recommended marker properties:

• long;
• opaque;
• random;
• ASCII-only;
• unique per installation;
• preferably unique per email type.

Example format:

ID: 

Do not publish real marker tokens in public documentation, screenshots or issue reports.

---

Critical email safety patterns

If Never Delay Critical Emails is enabled, emails matching critical subject, message or recipient patterns bypass all delays and are sent immediately.

Use this for:

• password reset emails;
• verification links;
• OTP / 2FA codes;
• account invitations;
• login alerts;
• security alerts;
• urgent billing messages;
• urgent system messages.

This prevents accidental delays for emails that users expect immediately.

---

Dry-run mode

Dry-run mode lets you test rules without changing actual email timing.

When Dry Run is enabled:

• rules are evaluated;
• matching decisions are logged;
• calculated delay is logged;
• the real outgoing email is not delayed by the rule.

Recommended rollout:

1. Enable Email Flow.
2. Keep Dry Run enabled.
3. Create rules.
4. Trigger test emails.
5. Check Email Flow Log.
6. Confirm which rules matched.
7. Confirm calculated delays.
8. Disable Dry Run only after matches are confirmed.

Dry-run mode is especially useful before introducing random delay ranges or rules that target production customer emails.

---

Logs

When logging is enabled, the app writes diagnostic records to Email Flow Log.

Logs help verify:

• which rule matched;
• whether dry-run mode was active;
• which action was selected;
• which delay was calculated;
• whether priority was changed;
• whether an email was bypassed as critical;
• whether no matching rule was found.

Logs are intended for diagnostics and operational review.

They should not contain secrets.

---

Backend simulator

From bench console:

frappe.get_attr("frappe_email_flow.api.simulate_email_flow")(
    subject="Your report is ready",
    recipients="customer@example.com",
    reference_doctype="Example Document",
    reference_name="EXAMPLE-0001",
    has_attachment="Yes",
)

Use the simulator to test rule matching logic before relying on production email flow.

---

Security model

Frappe Email Flow follows a conservative email-queue security model.

No external calls in the hook

The app does not call external APIs inside the Email Queue.before_insert hook.

This keeps queue insertion fast and avoids provider lock-in.

Fail-open behaviour

When Fail Open is enabled, unexpected rule evaluation failures should not block standard Frappe email sending.

This is recommended for production systems unless you intentionally need fail-closed behaviour.

Critical email protection

Password resets, verification links, OTP / 2FA codes, account invitations, login alerts and security messages should bypass delays.

Marker protection

Markers are routing hints, not secrets.

Do not store confidential information