Skip to content

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 RentReminderService and include EMAIL with 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-url and /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_DUE or NotificationTemplate.PAYMENT_OVERDUE;
  • payload type stays PAYMENT_DUE or PAYMENT_OVERDUE to satisfy the notification key constraint;
  • rule identity is stored in payload.reminderRule: rent_due_before_N, rent_due_today, rent_overdue_1, or rent_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.EMAIL to the same in-app/push notification call;
  • respect notifyEmail through NotificationService.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: RentReminderServiceTest failed to compile before RentReminderService existed;
  • 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 [email protected]
  • 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 7e44856 fixed invitation email fallback handling for encrypted property records whose plaintext property name is null;
  • backend pipeline 2631443704 passed 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-runtime is not authorized for ses:SendEmail on the mamnajem.pl SES identity.

Infrastructure fix:

  • architecture commit 0b57572 grants the integration runtime IAM user ses:SendEmail on local.ses_identity_arn;
  • architecture pipeline 2631485895 passed, including terraform_apply_integration;
  • post-deploy browser health check returned {"status":"UP","groups":["liveness","readiness"]}.

Final result:

  • disposable smoke run 20260626095726-60a751 created owner trial, encrypted bank account, encrypted property with no plaintext name, pending lease, tenant stub, and tenant invitation;
  • invitation creation returned HTTP 201 for invitation e597a5b9-1344-41c5-b2ed-cbfc7c25e95e;
  • CloudWatch /mamnajem/integration/app recorded Invitation 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.