Email notifications

Iskue turns ticket activity into in-app notifications, and can additionally deliver them by email. Email delivery is off by default: until you enable it, every message that would have been sent is written to the backend log instead, so you can adopt the rest of this page at your own pace. Notification email to team members is plain text; customer-facing service-desk email is multipart (plain text plus an HTML alternative) with RFC 5322 threading headers so replies group correctly in the customer's mail client.

How sending works

The switch is the MAIL_ENABLED environment variable, which maps to the app.mail.enabled property. With it unset or false, a logging sender is active and each would-be email appears in the backend log as Email (disabled, app.mail.enabled=false) to=… subject=…. With MAIL_ENABLED=true, an SMTP sender takes over, configured through Spring Boot's standard spring.mail.* properties (the SPRING_MAIL_* environment variables below). Sending is asynchronous and failure-tolerant: an SMTP error is logged as a warning (Failed to send email to …) and never fails the API request that triggered it.

Enable SMTP delivery

For the standard Docker deployment, set the values in the .env file next to docker-compose.yml (start from the committed .env.example):

MAIL_ENABLED=true
SPRING_MAIL_HOST=smtp.example.com
SPRING_MAIL_PORT=587
SPRING_MAIL_USERNAME=iskue-mailer
SPRING_MAIL_PASSWORD=your-smtp-password
MAIL_FROM=issuehub@example.com

# docker-compose.override.yml — merged automatically by docker compose
services:
  backend:
    environment:
      SPRING_MAIL_HOST: ${SPRING_MAIL_HOST}
      SPRING_MAIL_PORT: ${SPRING_MAIL_PORT:-587}
      SPRING_MAIL_USERNAME: ${SPRING_MAIL_USERNAME}
      SPRING_MAIL_PASSWORD: ${SPRING_MAIL_PASSWORD}
      MAIL_FROM: ${MAIL_FROM}
      EMAIL_INBOUND_ADDRESS: ${EMAIL_INBOUND_ADDRESS:-}
      PORTAL_BASE_URL: ${PORTAL_BASE_URL:-http://localhost:5173}

docker compose --profile full up -d --build

Which events send mail

Recipients are decided by the project's notification scheme: a named set of rules mapping each event type to recipient types. Every project references a scheme; a project without one falls back to the built-in default scheme. The event catalogue and the default scheme's rules are:

A rule's recipient type is one of CURRENT_ASSIGNEE, REPORTER, WATCHERS, ALL_PROJECT_MEMBERS, PROJECT_ROLE, SPECIFIC_USER or GROUP. Named users and group members are only notified if they are members of the project, so schemes cannot leak activity across visibility boundaries. Recipients are de-duplicated and the acting user is always excluded — nobody is emailed about their own change.

Schemes are managed by instance admins at /api/v1/admin/notification-schemes (list, create, edit rules, set default; GET /api/v1/admin/notification-schemes/catalog returns the event and recipient catalogue). Project admins assign a scheme to their project through the project notification endpoint. Both are also available in the admin UI.

Per-user preferences

Each user chooses how notification email reaches them via an email mode: IMMEDIATE (one email per notification, the default), DAILY (a single daily digest of unread notifications) or NONE (in-app only). Users change this on the notifications page in the UI, or via the API:

curl -X PATCH http://localhost:8088/api/v1/users/me/preferences \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emailMode":"DAILY","digestGrouping":"BY_PROJECT"}'

• emailMode — IMMEDIATE, DAILY or NONE.
• digestGrouping — daily digest layout: FLAT (chronological, the default), BY_PROJECT or BY_TYPE.
• snoozeHours — a do-not-disturb window: any value from 1 to 336 suppresses all notifications (in-app and email) for that many hours; 0 clears it.
• Mutes — POST /api/v1/notification-prefs with an optional projectId and optional eventType silences matching events entirely, mentions included; omitting projectId means all projects, omitting eventType means all events. GET lists mutes, DELETE /api/v1/notification-prefs/{id} removes one.
• Deactivated accounts are never emailed.

The daily digest

A background sweeper checks every 60 seconds for DAILY-mode users whose digest period has elapsed (the app.digest.period-minutes application property, default 1440 — once a day) and sends each a single plain-text digest of their unread notifications, laid out per their digestGrouping. A user with nothing unread gets no email that period. The digest lists at most 20 lines and closes with … and N more. when there are more. On multi-node clusters the send slot is claimed atomically, so exactly one backend sends each digest.

Saved-filter subscription emails

Users can subscribe to a saved filter to receive its current results by email on the same cadence pattern (the app.filter-subscription.period-minutes property, default 1440). The filter's TQL query runs as the subscriber, so project access and restricted-ticket visibility apply exactly as in the UI. An empty result set sends nothing; results are capped at 20 lines with an overflow count. Subscribing and unsubscribing is done from the saved-filter UI or PUT/DELETE on /api/v1/filters/{id}/subscription.

Email templates

The three internal notification emails are rendered from templates that instance admins can override. Placeholders are literal {name} tokens replaced verbatim; an unknown token is left as-is so a typo is visible in a delivered email rather than silently vanishing.

# List templates (effective + default subject/body, placeholder list)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8088/api/v1/admin/email-templates

# Override the per-event template
curl -X PUT http://localhost:8088/api/v1/admin/email-templates/EVENT \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"subject":"[IssueHub] {ticketKey} — {event}","body":"{message}\n\nOpen the ticket: https://tracker.example.com/tickets/{ticketKey}"}'

# Restore the built-in default
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8088/api/v1/admin/email-templates/EVENT

Customer email (service desk and portal)

Separately from team notifications, Iskue emails external customer contacts to close the service-desk loop. A public agent reply on a customer's ticket — and a public automated reply posted by an automation rule — is emailed to the ticket's requester contact. These messages are multipart (text + HTML), carry threading headers so a ticket's messages group into one conversation, and are localised to the contact's stored locale.

• With EMAIL_INBOUND_ADDRESS set (for example support@example.com), each message's Reply-To becomes a per-ticket address such as support+KEY-123@example.com, so a customer reply threads back to the right ticket even if the subject was edited.
• With PORTAL_BASE_URL set, every reply notification carries a one-click unsubscribe link in its footer. Unsubscribing flags the contact; further reply notifications to that contact are suppressed. The endpoint is public and idempotent: POST /api/v1/email/unsubscribe/{token}, where the token is HMAC-signed — it cannot be forged or redirected at another contact.
• Issuing a portal link with ?notify=true emails it to the contact. This message is transactional and is sent even to unsubscribed contacts.

# Issue a portal link for a contact and email it to them
curl -X POST \
  "http://localhost:8088/api/v1/projects/SUP/contacts/$CONTACT_ID/portal-link?notify=true" \
  -H "Authorization: Bearer $TOKEN"

Verify and troubleshoot

• With mail disabled, confirm the dispatch path end-to-end by watching for Email (disabled, app.mail.enabled=false) to=… subject=… lines: docker logs -f issuehub-backend.
• With mail enabled, SMTP failures appear as Failed to send email to … warnings. Because sending is asynchronous, a misconfigured SMTP server never surfaces as an API error — the log is the only signal.
• No email for a specific user? Check, in order: their email mode (NONE sends nothing; DAILY batches into the digest), an active snooze, a matching mute, whether they were the actor (actors are never notified), and whether the project's notification scheme has a rule for that event type.
• CREATED and UPDATED are silent until an admin adds scheme rules for them — that is the shipped default, not a fault.