bench get-app https://github.com/devlpr-nitish/citrus-test

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=devlpr-nitish%2Fcitrus-test)](https://frappegems.com/gems/apps/devlpr-nitish/citrus-test)

Citrus

A custom Frappe app built on top of ERPNext that adds item-level email functionality — send the latest sales invoices for any item directly from the Item form.

---

Features

Send Sales Invoice Email (Item Form)

• A Send Email button is available under the Actions menu on the Item detail page.
• On click, a dialog prompts for the recipient email address (pre-filled with the logged-in user's email).
• The email is sent as a background job so the UI is never blocked.
• The email uses a custom Jinja email template (Item Sales Invoices) that includes a table of the latest 5 submitted Sales Invoices for the item, along with PDF attachments of each invoice.

Item Email Log (DocType)

Tracks every email send attempt with the following fields:

Field	Description
Item	The item the email was triggered from
Item Name	Auto-fetched
Recipient	The email address the mail was sent to
Status	Queued → Success or Failed
Queued At	Timestamp when the job was enqueued
Sent At	Timestamp when the email was successfully sent
Invoice Names	Newline-separated list of invoice names included
Error Message	Full traceback if the job failed

Accessible at: Citrus → Item Email Log

---

Tech Overview

Layer	File	Purpose
JS	public/js/item.js	Adds Actions button, shows prompt dialog, calls API via frappe.xcall
Python API	citrus/citrus/api.py	Whitelisted endpoint — creates log entry, enqueues background job
Background job	citrus/citrus/api.py (_send_email_background)	Fetches invoices, renders template, sends email, updates log
Email Template	fixtures/email_template.json	Jinja HTML template with invoice table (Item Sales Invoices)
DocType	citrus/doctype/item_email_log/	Tracks email send status
Hook	hooks.py (doctype_js)	Loads item.js into the Item form

---

Installation

Prerequisites

• A working Frappe bench with ERPNext installed
• Redis running (required for background jobs)
• Outgoing email configured in ERPNext (Settings → Email Domain)

Steps

cd /path/to/your/bench

# 1. Get the app (if not already present)
bench get-app citrus /path/to/citrus  # or git URL

# 2. Install the app on your site
bench --site  install-app citrus

# 3. Run migrations (creates the Item Email Log table)
bench --site  migrate

# 4. Import the Email Template fixture
bench --site  import-fixtures --app citrus

# 5. Build JS assets
bench build --app citrus

# 6. Restart
bench restart

---

Usage

1. Open any Item record in ERPNext.
2. Click Actions → Send Email.
3. Enter or confirm the recipient email address and click Send.
4. The email is queued — a blue alert appears with a link to the Item Email Log record.
5. Check the log record for Success or Failed status and any error details.

---

Development

Re-exporting fixtures after editing the Email Template in the UI

bench --site  export-fixtures --app citrus

Pre-commit hooks

cd apps/citrus
pre-commit install

Configured tools: ruff, eslint, prettier, pyupgrade

---

License

MIT