evidencija-rezija/sprints/email-worker.md

Context

E-mail worker in workspace email-worker has the following task:

• send e-mail verification requests
• send rent due notifications
• send utility bills due notifications

The worker runs every 60 seconds (can be modified via env variable). During each run it checks which e-mails it needs to send, composes appropriate e-mail text and sends them.

Standoff strategy & Priority

For each run there's budget which limits on total number of e-mails of all types which can be sent per one worker run. This provides a stand-off so that the remote mail server is not overwhelmed. Default budget is 10, which can be configured via env variable.

Budget is reset to initial value at beginning of each run. Budget should be decremented on each attempted e-mail send - even failed ones.

E-mail verification request have priority and are sent first.

Web App

This worker is a companion to the web app in workspace web-app. It connects to the same DB and uses same data structures.

In this document we use typescript types which can be found in /home/kneecola/projects/evidencija-rezija/web-app/app/lib/db-types.ts

DB structure

MongoDB has two collections:

• lokacije - described by BillingLocation type in db-types.ts
• userSettings - described by UserSettings type in db-types.ts

Note: UserSettings shares the same userId value with BillingLocation, which can be used to find the appropriate records.

DB connection

• connect to the db the same way as in web-app workspace - you can re-use the same connection for processing each e-mail type
• in case of failed connection break current work and try again in the next worker interval (at the beginning of each run connect, and on run end disconnect)

Sending e-mail verification requests

The process of sending e-mail verification requests is as follows:

• connect to MongoDB (see how web app in web-app workspace connects to the DB)
• fetch all BillingLocations from lokacije collection (see locationActions.ts in web-app workspace) - filter only records which satisfy the following:
  • yearMonth.year and yearMonth.month equal to current year and month
  • tenantEmailStatus is equal to EmailStatus.Unverified
• for each record found
  • check the e-mail budget counter -> if the value is 0 then exit
  • compile an e-mail containing the content listed below
  • send the e-mail
    • if send OK set tenantEmailStatus to EmailStatus.VerificationPending
    • if send failed set tenantEmailStatus to EmailStatus.VerificationFailed
  • decrement the e-mail budget counter

Verification requests E-mail content

Subject: Please verify your e-mail address From rezije.app noreply@rezije.app To: BillingLocation-tenantEmail

<p>Hello ${tenantName}!</p>

<p>You have received this e-mail because your landlord <strong>${userSettings.ownerName}</strong> wants to send you rent and utility bills invoices via rezije.app</p>

<p><strong>rezije.app</strong> is an online app which helps property owners to manage expenses related to properties they lease.</p>

<p>Before the app can start sending you rent due and utility bills emails we need your verification.</p>

<p>To verify that you want to receive these notifications please click on the following link: <a href="https://rezije.app/email/verify/${shareId}">Verify</a></p>

<p>You can ignore this email if you don't want to receive notifications. You can also unsubscribe at any time using the link included in every notification email you receive.</p>

<p>Thank you!</p>

<a href="https://rezije.app" target="_blank">rezije.app</a>

Notes:

• the shareId is generated using algorithm found in /home/kneecola/projects/evidencija-rezija/web-app/app/lib/shareChecksum.ts
• the verify link click is handled by the web app in web-app workspace
• if userSettings.ownerName cannot be found replace it with an empty string

Sending rent due notifications

The process of sending rent-due e-mail notifications is as follows:

• check the e-mail budget counter -> if the value is 0 then exit
• connect to MongoDB (see how web app in web-app workspace connects to the DB)
• fetch all BillingLocations from lokacije collection (see locationActions.ts in web-app workspace) - filter only records which satisfy the following:
  • yearMonth.year and yearMonth.month equal to current year and month
  • tenantEmailStatus is equal to EmailStatus.Verified
  • rentNotificationEnabled === true
  • rentDueDay = current day (1-31) in CET timezone
  • rentNotificationStatus === undefined OR rentNotificationStatus === null
• for each record found
  • check the e-mail budget counter -> if the value is 0 then exit
  • compile an e-mail containing the content listed below
  • send the e-mail
    • if send OK set rentNotificationStatus to sent
    • if send failed set rentNotificationStatus to failed
  • decrement the e-mail budget counter

Rent due notifications E-mail content

Subject: Rent due for ${location.tenantName} From rezije.app noreply@rezije.app Address: BillingLocation-tenantEmail

<p>Hello ${location.tenantName}!</p>

<p>Your rent for the apartment ${location.name} is due today.</p>

<p>For details and payment options please click the following link: <a href="https://rezije.app/share/rent-due/${shareId}">Rent details</a></p>

<p>Thank you!</p>

<p><a href="https://rezije.app" target="_blank">rezije.app</a></p>

<p style="font-size:.7em">If you do no longer want to receive these notifications please click the following link: <a href="https://rezije.app/email/unsubscribe/${shareId}">Unsubscribe</a></p>

Sending utility bills due notifications

The process of bills due notifications e-mail is as follows:

• check the e-mail budget counter -> if the value is 0 then exit
• connect to MongoDB (see how web app in web-app workspace connects to the DB)
• fetch all BillingLocations from lokacije collection (see locationActions.ts in web-app workspace) - filter only records which satisfy the following:
  • yearMonth.year and yearMonth.month equal to current year and month
  • tenantEmailStatus is equal to EmailStatus.Verified
  • billsNotificationEnabled === true
  • billsNotificationStatus === 'scheduled'
• for each record found
  • check the e-mail budget counter -> if the value is 0 then exit
  • compile an e-mail containing the content listed below
  • send the e-mail
    • if send OK set billsNotificationStatus to sent
    • if send failed set billsNotificationStatus to failed
  • decrement the e-mail budget counter

Utility bills due notifications E-mail content

Subject: Utility bills due for ${location.tenantName} From rezije.app noreply@rezije.app Address: BillingLocation-tenantEmail

<p>Hello ${location.tenantName}!</p>

<p>Your utility bills for the apartment ${location.name} are due today.</p>

<p>For details and payment options please click the following link: <a href="https://rezije.app/share/bills-due/${shareId}">Utility Bills</a></p>

<p>Thank you!</p>

<p><a href="https://rezije.app" target="_blank">rezije.app</a></p>

<p style="font-size:.7em">If you do no longer want to receive these notifications please click the following link: <a href="https://rezije.app/email/unsubscribe/${shareId}">Unsubscribe</a></p>

Logging

• log all errors
• log info at beginning of each worker run
• log stats at each of e-mail type processed (how many e-mails were sent of each type)

Race condition handling

Web app does not update the same fields as e-mail worker (review code & verify). Updates should be atomic and just in time. Do not batch many updates together as it might postpone the update.

E-mail provider

E-mails will be sent via Mailgun online service using its API.

Use the following API Key = d660e320e0cdeecc125d4ecd6bc5cd66-e61ae8dd-01bdd61a