Frappe Notification System

Quick Reference

frappe.sendmail()

frappe.publish_realtime()

frappe.desk.form.assign_to.add()

frappe.get_doc({"doctype": "ToDo", ...})

doc.add_comment("Comment", text)

doc.add_tag("tag_name")

Decision Tree

What notification mechanism do you need?
│
├─ Email on document event (no code)?
│  └─ Notification DocType → Channel: Email
│
├─ Programmatic email with custom logic?
│  └─ frappe.sendmail() in server script or hook
│
├─ Real-time in-app notification?
│  ├─ No-code → Notification DocType → Channel: System Notification
│  └─ Programmatic → frappe.publish_realtime()
│
├─ SMS on document event?
│  └─ Notification DocType → Channel: SMS (requires SMS Settings)
│
├─ Assign document to user?
│  ├─ No-code → Assignment Rule DocType
│  └─ Programmatic → frappe.desk.form.assign_to.add()
│
├─ Recurring document creation?
│  └─ Auto Repeat DocType
│
└─ Add comment or tag?
   ├─ Comment → doc.add_comment("Comment", text="...")
   └─ Tag → doc.add_tag("tag_name")

Notification DocType

The Notification DocType enables no-code alerts across four channels.

Event Triggers

Condition Syntax

ALWAYS use Python expressions in the Condition field:

# Status-based
doc.status == "Open"

# Date-based
doc.due_date == nowdate()

# Threshold-based
doc.grand_total > 40000

# Combined
doc.status == "Overdue" and doc.grand_total > 10000

Available context:

doc

nowdate()

frappe.utils.*

Recipient Configuration

Jinja Message Template

<h3>Order Overdue</h3>
<p>Transaction {{ doc.name }} has exceeded its due date.</p>

{% if comments %}
Last comment: {{ comments[-1].comment }} by {{ comments[-1].by }}
{% endif %}

<ul>
  <li>Customer: {{ doc.customer }}</li>
  <li>Amount: {{ doc.grand_total }}</li>
</ul>

Template variables:

{{ doc }}

{{ doc.fieldname }}

{{ comments }}

{{ nowdate() }}

Attach Print

Set Attach Print to include a PDF of the document. Select a Print Format for custom layout.

frappe.sendmail(): Programmatic Email

frappe.sendmail(
    recipients=["user@example.com"],       # list of email addresses
    subject="Invoice Due",                  # email subject
    message="<p>Your invoice is due.</p>",  # HTML body
    template="invoice_reminder",            # Jinja template name (optional)
    args={"customer": "ACME"},              # template context variables
    attachments=[{"fname": "inv.pdf", "fcontent": pdf_bytes}],
    reference_doctype="Sales Invoice",      # links email to document
    reference_name="SINV-00001",
    delayed=True,                           # queue via Email Queue (default)
    now=False,                              # True = send immediately, skip queue
    sender="noreply@example.com",           # override sender
    cc=["manager@example.com"],
    bcc=["audit@example.com"],
    reply_to="support@example.com",
    expose_recipients="header",             # show recipients in email header
)

Rules:

• ALWAYS set

  reference_doctype

  and

  reference_name

  when the email relates to a document — this links the email in the document timeline.
• NEVER set

  now=True

  in production — it blocks the request. Use

  delayed=True

  (default) to queue via Email Queue.
• ALWAYS ensure an Email Account with "Enable Outgoing" is configured before calling

  frappe.sendmail

  .

Email Queue

Emails are queued in the Email Queue DocType and sent by the scheduler. Check queue status:

# Check pending emails
pending = frappe.get_all("Email Queue", filters={"status": "Not Sent"}, limit=10)

frappe.publish_realtime(): System Notifications

frappe.publish_realtime(
    event="msgprint",                      # event name
    message={"msg": "Task completed!"},    # dict payload
    user="user@example.com",               # target specific user
    doctype="Sales Invoice",               # broadcast to doctype room
    docname="SINV-00001",                  # broadcast to document room
    after_commit=True,                     # emit after transaction commits
)

Room Types

user:{email}

user=

doctype:{dt}

doc:{dt}/{dn}

all

task_progress:{id}

Built-in Events

msgprint

list_update

docinfo_update

progress

ALWAYS set

after_commit=True

Assignment Rules

Auto-assign documents to users based on conditions (no code).

Configuration Fields

Programmatic Assignment

from frappe.desk.form.assign_to import add, remove, close, clear

# Assign
add({
    "assign_to": ["user@example.com"],
    "doctype": "Task",
    "name": "TASK-00001",
    "description": "Please review this task",
    "priority": "High",
    "date": "2025-12-31",
})

# Remove assignment (cancels ToDo)
remove("Task", "TASK-00001", "user@example.com")

# Close assignment (only assignee can close)
close("Task", "TASK-00001", "user@example.com")

# Clear all assignments
clear("Task", "TASK-00001")

NEVER call

close()

Auto Repeat

Creates recurring copies of documents on a schedule.

ALWAYS set an End Date on Auto Repeat — open-ended schedules create documents indefinitely and are difficult to debug.

ToDo API

# Create ToDo directly
todo = frappe.get_doc({
    "doctype": "ToDo",
    "allocated_to": "user@example.com",
    "assigned_by": frappe.session.user,
    "description": "Review the quarterly report",
    "priority": "Medium",
    "date": "2025-12-31",
    "status": "Open",
    "reference_type": "Task",
    "reference_name": "TASK-00001",
}).insert(ignore_permissions=True)

ToDo statuses:

Open

Closed

Cancelled

Comments and Tags

# Add comment (appears in document timeline)
doc.add_comment("Comment", text="Reviewed and approved")
doc.add_comment("Edit", "Values changed")

# Add/get tags
doc.add_tag("urgent")
tags = doc.get_tags()  # returns list of tag strings

Version Differences

frappe.publish_realtime

See Also

• references/email-system.md — Email Account, Email Queue, Communication linking, Newsletter, Notification Log
• references/examples.md — Full notification workflow examples
• references/anti-patterns.md — Common mistakes and fixes
• references/api-reference.md — Complete API signatures

• frappe-core-database

  — Database operations referenced in notifications

• frappe-core-permissions

  — Permission model for notification access