Skip to content

Communications

The apps.communications module provides multi-channel templated messaging for borrower notifications, collection dunning, and operational communications.

Channels

Channel Provider(s) Use Cases
Email SendGrid (default), SMTP Statements, confirmations, reminders, notices
SMS Twilio Payment reminders, urgent alerts
Letter Lob Formal notices, regulatory correspondence
In-app Internal (no external provider) Portal notifications

Each channel is backed by a provider protocol (see Provider Pattern).

Template System

Jinja2 Templates

Communication templates use Jinja2 for dynamic content rendering:

Field Description
channel Email, SMS, letter, or in-app
template_type Type of communication (see below)
program Optional FK to lending program
language Template language (ISO 639-1)
subject_template Jinja2 template for subject line
body_template Jinja2 template for message body
is_active Whether the template is available for use

Template Types

Type Description
statement Periodic account statement
payment_confirmation Payment received confirmation
payment_reminder Upcoming payment reminder
late_notice Past-due payment notice
payoff_quote Payoff quote details
modification_offer Loan modification proposal
forbearance_approval Forbearance approval notification
deferment_approval Deferment approval notification
welcome Welcome/onboarding message
goodbye Account closure notification
regulatory_disclosure Required regulatory notices
custom Custom/ad-hoc communications

Template Context Variables

Templates receive typed context variables:

Variable Type Description
borrower Borrower Borrower details
loan Loan Loan details
payment Payment Payment details (if applicable)
fee Fee Fee details (if applicable)
payoff PayoffQuote Payoff details (if applicable)
servicer Tenant Servicer/tenant information
today date Current date

Locale-Aware Filters

Jinja2 filters for formatting within templates:

Filter Example Description
currency {{ amount \| currency(locale) }} Currency formatting
date {{ due_date \| date(locale) }} Date formatting
number {{ count \| number(locale) }} Number formatting
percent {{ rate \| percent(locale) }} Percentage formatting

Per-Language Variants

Templates support per-language variants with English fallback:

  1. resolve_template_for_language() looks for a template matching the requested language
  2. If no match, falls back to English (en)
  3. send_communication() reads borrower.language_preference for automatic language selection

Delivery Flow

1. Service calls send_communication()
       │
2. Resolve template for borrower's language
       │
3. Render template with context variables
       │
4. Check do_not_contact flag → BLOCK if True
       │
5. Dispatch via Celery task (async)
       │
6. Route to channel provider
       │
7. Track delivery status

Delivery Statuses

Status Description
pending Queued for delivery
sending Being sent to provider
sent Accepted by provider
delivered Confirmed delivered to recipient
failed Delivery failed
bounced Email bounced

Communication Log

Every communication attempt is recorded in CommunicationLog regardless of outcome:

Field Description
borrower FK to borrower
loan FK to loan (if applicable)
channel Delivery channel
recipient Email address, phone number, or mailing address
subject Rendered subject line
body Rendered message body
status Delivery status
provider_name Which provider handled delivery
provider_message_id Provider's tracking ID
error_message Error details (if failed)
triggered_by What triggered this communication (e.g., "dunning", "manual")

Provider Webhook Consumption

Providers send real-time delivery status updates via webhooks:

  • SendGrid: Delivery, bounce, open, click events
  • Twilio: Delivery, failure status callbacks

These webhooks update the CommunicationLog status in real time.

Features

Batch Send

Send the same template to multiple borrowers at once. Used for:

  • Mass payment reminders
  • Regulatory notices
  • Campaign communications (see Case Management)

Preview Mode

Render a template without sending it --- useful for reviewing content before dispatch.

Enforcement Rules

do_not_contact

Borrowers with do_not_contact = True receive zero automated communications. This is enforced as the final check before dispatch.

communication_preference

The borrower's communication_preference field determines their preferred channel. The system respects this preference, falling back to email if the preferred channel is unavailable.

Dunning Suppression

Dunning communications are suppressed during certain loan sub-statuses:

  • in_forbearance
  • in_deferment
  • in_bankruptcy
  • Active disputes

See Collections for dunning schedule details.

See Also