Deposit Release Proposal Notification

When a deposit release is proposed, every acknowledgement party — tenants and the landlord — is automatically notified via email and an in-app notification. This workflow removes the need for manual communication and ensures all parties have everything they need to respond within the required deadline.

How It Works

Trigger

The notification fires once, at the moment the deposit release transitions from draft to proposed. This transition is made by calling the propose mutation on a depositRelease record.

draft  ──► proposed  ←── notification fires here

No notification is sent for draft saves, edits, or any subsequent status transitions.

Recipients

Every party listed on the deposit release's acknowledgement rows receives a notification. This includes:

• Tenants — all tenants attached to the release's acknowledgements.
• Landlord — the landlord associated with the deposit release.

Each recipient receives an individual, unique notification — tokens and links are scoped per recipient and are not shared.

Notification Channels

Each recipient receives both:

1. Email — sent to the recipient's registered email address.
2. In-app notification — surfaced within the platform UI.

Both channels carry the same core information (see Notification Content below).

Notification Content

Each notification includes:

Content	Description
Unique acknowledgement link	A tokenised URL scoped to the individual recipient. Used to submit their acknowledgement response.
Deduction summary	A breakdown of all proposed deductions: description and amount for each line item.
Response deadline	The date by which the recipient must acknowledge or dispute the proposal.

Audit Trail

When a notification is sent, a notified_at timestamp is written to the corresponding depositReleaseAcknowledgement row for that recipient. This provides a verifiable record that the party was notified, which is relevant for compliance and dispute timelines.

Entities

Entity	How It Is Used
depositReleases	The source record. The workflow reads status, deductions, and acknowledgement parties from this record.
depositReleaseAcknowledgements	One row per recipient. The workflow stamps notified_at on each row when the notification is dispatched.
depositReleaseDeductions	Provides the deduction line items included in the notification body.
tenants	Supplies contact details and identity for tenant recipients.
landlords	Supplies contact details and identity for the landlord recipient.
organizations	Provides organisational context (e.g. branding, sender identity) for outbound messages.

Compliance Notes

• The notified_at timestamp on each depositReleaseAcknowledgement row creates an auditable record of when each party was informed, supporting compliance with the Renters' Rights Act.
• Unique per-recipient acknowledgement tokens ensure that responses are authenticated and attributable to the correct party.
• The deadline communicated in the notification is derived from the deposit release record; ensure the deadline is set correctly before calling propose.

Prerequisites

Before calling the propose mutation, ensure:

1. The depositRelease record is in draft status.
2. At least one depositReleaseAcknowledgement row exists, with valid tenant and/or landlord references.
3. All depositReleaseDeductions are finalised — the notification content is generated at send time and will reflect whatever deductions exist at that moment.
4. A response deadline is set on the release.
5. All recipients have valid, reachable email addresses registered in the platform.