Email Workflow Wiring¶
Last verified: 2026-06-26.
This document records the EP6-T5 backend workflow wiring for launch transactional email. It builds on Email delivery implementation and the copy contract in Launch email templates.
Backend Behavior¶
Commit 1580cf2 wires launch workflow email in the backend:
- tenant invitation creation sends a direct SES email to the invitation address;
- registered invitees still receive the existing in-app/push invitation notification;
- rent reminders run from
RentReminderServiceand includeEMAILwith in-app and push; - payment proof notifications include
EMAIL; - handover pending-confirmation notifications include
EMAIL; - final settlement initiated and pending-confirmation notifications include
EMAIL.
The direct invitation email does not create a notification row because
notifications.user_id is required and an invitee may not have an account yet.
It still uses the same SES sender, sender address, and PII-safe logging boundary.
Recipient And Preference Rules¶
Invitation email:
- recipient is the invitation email address;
- send even when no MamNajem user exists yet;
- provider failure is logged by invitation id and does not roll back invitation creation;
- CTA URL is built from
notification.email.app-urland/invitations/accept/{code}.
Rent reminders:
- due-before and due-today reminders go to accepted tenant users;
- overdue day 1 and overdue day 7 reminders go to accepted tenant users and the lease owner;
- reminders use
NotificationTemplate.PAYMENT_DUEorNotificationTemplate.PAYMENT_OVERDUE; - payload
typestaysPAYMENT_DUEorPAYMENT_OVERDUEto satisfy the notification key constraint; - rule identity is stored in
payload.reminderRule:rent_due_before_N,rent_due_today,rent_overdue_1, orrent_overdue_7; - duplicate sends are skipped per recipient, payment request, and reminder rule.
Payment proof, handover, and settlement email:
- use existing workflow recipient selection;
- add
NotificationChannel.EMAILto the same in-app/push notification call; - respect
notifyEmailthroughNotificationService.scheduleMultiChannel(...).
Config¶
Backend config:
notification:
email:
app-url: ${NOTIFICATION_EMAIL_APP_URL:${APP_URL:https://mamnajem.pl}}
rent-reminders:
fixed-delay-ms: ${RENT_REMINDERS_FIXED_DELAY_MS:3600000}
The integration Spring profile defaults the app URL to:
notification:
email:
app-url: ${NOTIFICATION_EMAIL_APP_URL:${APP_URL:https://web-integration.mamnajem.pl}}
Verification¶
Local verification:
- red test first:
RentReminderServiceTestfailed to compile beforeRentReminderServiceexisted; - focused green test:
mvn -q -Djacoco.skip=true -Dtest=RentReminderServiceTest,InvitationServiceTest,HandoverProtocolServiceTest,FinalSettlementServiceTest,PaymentReceiptServiceTest test; - full backend verification:
mvn -q verify.
GitLab verification:
- backend pipeline
2628301591; - commit
1580cf2; environment-contract: success;gitleaks: success;semgrep: success;maven-build-artifacts: success;api-backwards-compatibility-check: success;maven-test: success;maven-deploy-integration-host: success.
Post-deploy browser verification:
https://integration.mamnajem.pl/actuator/health;- response:
{"status":"UP","groups":["liveness","readiness"]}.
2026-06-26 Live Workflow Smoke¶
Smoke target:
- integration API:
https://integration.mamnajem.pl/v1 - disposable owner: Cognito-confirmed integration test user
- recipient: AWS SES mailbox simulator success address
success@simulator.amazonses.com - workflow: owner trial -> bank account -> encrypted property -> pending lease -> tenant stub -> tenant invitation
- note (2026-11-08): this record predates the removal of end-to-end encryption; properties now always have a plain name.
Initial result:
- backend commit
7e44856fixed invitation email fallback handling for encrypted property records whose plaintext property name isnull; - backend pipeline
2631443704passed and deployed to integration; - post-deploy browser health check returned
{"status":"UP","groups":["liveness","readiness"]}; - post-deploy invitation creation returned HTTP 201, but CloudWatch recorded
SES failure because the integration runtime IAM principal
mamnajem-integration-integration-runtimeis not authorized forses:SendEmailon themamnajem.plSES identity.
Infrastructure fix:
- architecture commit
0b57572grants the integration runtime IAM userses:SendEmailonlocal.ses_identity_arn; - architecture pipeline
2631485895passed, includingterraform_apply_integration; - post-deploy browser health check returned
{"status":"UP","groups":["liveness","readiness"]}.
Final result:
- disposable smoke run
20260626095726-60a751created owner trial, encrypted bank account, encrypted property with no plaintextname, pending lease, tenant stub, and tenant invitation; - invitation creation returned HTTP 201 for invitation
e597a5b9-1344-41c5-b2ed-cbfc7c25e95e; - CloudWatch
/mamnajem/integration/apprecordedInvitation email sent invitationId=e597a5b9-1344-41c5-b2ed-cbfc7c25e95e providerMessageId=0102019f03622f37-f016aa7a-0feb-4b12-ad18-237798b9c26e-000000; - disposable Cognito users were deleted after the smoke.
The email release gate is now Pass for launch-scope SES invitation delivery
on integration.