Communications API¶

Multi-channel messaging: templates, sending, batch operations, delivery tracking, auto-responses, and inbound webhooks.

Base permission: IsViewerOrAbove (read), IsLoanOfficerOrAbove (write)

Communication Templates¶

Jinja2-based templates for email, SMS, letter, and in-app messages.

Method	Path	Description	Permission
`GET`	`/communication-templates`	List templates	`IsViewerOrAbove`
`GET`	`/communication-templates/{id}`	Get template	`IsViewerOrAbove`
`POST`	`/communication-templates`	Create template	`IsAdminOrAbove`
`PUT`	`/communication-templates/{id}`	Update template	`IsAdminOrAbove`
`DELETE`	`/communication-templates/{id}`	Archive template	`IsAdminOrAbove`

Create Template¶

POST /api/v1/communication-templates

{
  "name": "Payment Reminder",
  "template_type": "payment_reminder",
  "channel": "email",
  "language": "en",
  "program_id": "661f9511-f3ac-52e5-b827-557766551111",
  "subject": "Payment Due - {{ loan.loan_number }}",
  "body": "Dear {{ borrower.first_name }},\n\nYour payment of {{ payment_amount | currency(locale) }} is due on {{ due_date | date(locale) }}.\n\nThank you,\n{{ tenant.name }}"
}

Template Variables¶

Templates have access to these context variables:

Variable	Description
`borrower`	Borrower profile (name, email, phone)
`loan`	Loan details (number, balance, rate, status)
`tenant`	Tenant name and branding
`payment_amount`	Payment amount due
`due_date`	Payment due date
`locale`	Tenant locale for formatting

Template Filters¶

Filter	Usage	Description
`currency`	`{{ amount \\| currency(locale) }}`	Locale-aware currency formatting
`date`	`{{ date \\| date(locale) }}`	Locale-aware date formatting
`number`	`{{ value \\| number(locale) }}`	Locale-aware number formatting
`percent`	`{{ rate \\| percent(locale) }}`	Percentage formatting

Sending¶

Send Communication¶

Send a single communication to a borrower.

POST /api/v1/communications/send

{
  "template_id": "...",
  "borrower_id": "...",
  "loan_id": "...",
  "channel": "email",
  "context": {
    "custom_field": "custom_value"
  }
}

Enforcement rules applied:

Checks do_not_contact flag --- blocked if true
Checks borrower's communication_preference --- blocked if channel is opted out
Checks suppression rules --- blocked if borrower has recent communication of same type

Send Batch¶

Send a communication to multiple borrowers.

POST /api/v1/communications/send-batch

{
  "template_id": "...",
  "borrower_ids": ["...", "...", "..."],
  "channel": "email"
}

Preview¶

Render a template without sending.

POST /api/v1/communications/preview

{
  "template_id": "...",
  "borrower_id": "...",
  "loan_id": "..."
}

Response:

{
  "subject": "Payment Due - LN-0001",
  "body": "Dear John,\n\nYour payment of $312.50 is due on January 15, 2026.\n\nThank you,\nAcme Lending",
  "channel": "email"
}

Check Communication Compliance¶

Check if a communication can be sent to a borrower.

POST /api/v1/communications/can-interact

{
  "borrower_id": "...",
  "channel": "email"
}

Response:

{
  "can_interact": true,
  "reasons": []
}

Or:

{
  "can_interact": false,
  "reasons": ["do_not_contact", "channel_opted_out"]
}

Communication Logs¶

Method	Path	Description	Permission
`GET`	`/communication-logs`	List all logs	`IsViewerOrAbove`
`GET`	`/communication-logs/{id}`	Get log entry	`IsViewerOrAbove`

Each log entry records the template, channel, recipient, rendered content, delivery status, and timestamps.

Auto-Responses¶

Automated response rules for inbound messages.

Method	Path	Description	Permission
`GET`	`/auto-responses`	List auto-response rules	`IsViewerOrAbove`
`GET`	`/auto-responses/{id}`	Get auto-response	`IsViewerOrAbove`
`POST`	`/auto-responses`	Create auto-response	`IsAdminOrAbove`
`PUT`	`/auto-responses/{id}`	Update auto-response	`IsAdminOrAbove`
`DELETE`	`/auto-responses/{id}`	Delete auto-response	`IsAdminOrAbove`

Inbound Webhooks¶

Receive delivery status updates and inbound messages from providers.

Method	Path	Description	Permission
`POST`	`/communications/webhooks/delivery-status`	Process delivery status	Provider-authenticated
`POST`	`/communications/webhooks/inbound/sms`	Receive inbound SMS	Provider-authenticated
`POST`	`/communications/webhooks/inbound/email`	Receive inbound email	Provider-authenticated

These endpoints are called by email/SMS providers (SendGrid, Twilio) to report delivery status changes and inbound messages.

Communication Channels¶

Channel	Provider	Description
`email`	SendGrid, SMTP	Email messages
`sms`	Twilio	SMS text messages
`letter`	(configurable)	Physical mail
`in_app`	Internal	In-app notifications