Email update (#17)

* Email styling: stronger headings, add Grid Imported Today, README screenshot

* Add Zappi data to startup email

Author: deadl0ck

README.md

@@ -985,6 +985,8 @@ On a good solar day you expect: a tall stacked bar, a Green forecast strip, a lo
 
 ## Email Notifications
 
+![Example mode-change notification email](docs/images/email_example.png)
+
 When the scheduler issues a mode-change command, it sends an email notification with:
 
 - success or failure status

docs/images/email_example.png

@@ -98,24 +98,28 @@ async def get_daily_totals(self, target_date: date) -> dict[str, Any] | None:
         """
         records = await self._client.get_daily_history(target_date)
         if not records:
-            return {"total_kwh": 0.0, "diverted_kwh": 0.0, "boosted_kwh": 0.0}
+            return {"total_kwh": 0.0, "diverted_kwh": 0.0, "boosted_kwh": 0.0, "grid_imported_kwh": 0.0}
 
         # myenergi history API returns energy values in joules.
         # Divide by 3,600,000 to convert to kWh.
         # h1d = solar energy diverted to EV; h1b = grid energy boosted to EV.
-        # imp = total site grid import — NOT EV-specific, excluded here.
+        # imp = total site grid import (whole-house, not EV-specific).
         total_div_j = 0
         total_boost_j = 0
+        total_import_j = 0
         for record in records:
             total_div_j += int(record.get("h1d", 0) or 0)
             total_boost_j += int(record.get("h1b", 0) or 0)
+            total_import_j += int(record.get("imp", 0) or 0)
 
         diverted_kwh = total_div_j / 3_600_000.0
         boosted_kwh = total_boost_j / 3_600_000.0
         total_kwh = diverted_kwh + boosted_kwh
+        grid_imported_kwh = total_import_j / 3_600_000.0
 
         return {
             "total_kwh": round(total_kwh, 3),
             "diverted_kwh": round(diverted_kwh, 3),
             "boosted_kwh": round(boosted_kwh, 3),
+            "grid_imported_kwh": round(grid_imported_kwh, 3),
         }

integrations/zappi_interaction.py

@@ -171,6 +171,19 @@ async def create_scheduler_interaction(mode_names: dict[int, str]) -> SigenInter
                     exc,
                 )
             startup_mode_raw, startup_soc, startup_solar_today_kwh = await log_current_mode_on_startup(sigen, mode_names)
+            startup_zappi_status = None
+            startup_zappi_daily = None
+            try:
+                from integrations.zappi_auth import get_zappi_interaction
+                from zoneinfo import ZoneInfo
+                from config.settings import LOCAL_TIMEZONE
+                zappi = get_zappi_interaction()
+                if zappi is not None:
+                    startup_zappi_status = await zappi.get_live_status()
+                    local_today = datetime.now(ZoneInfo(LOCAL_TIMEZONE)).date()
+                    startup_zappi_daily = await zappi.get_daily_totals(local_today)
+            except Exception as exc:
+                logger.warning("[SCHEDULER] Could not fetch Zappi data for startup email: %s", exc)
             await notify_startup_email(
                 current_mode_raw=startup_mode_raw,
                 battery_soc=startup_soc,
@@ -179,6 +192,8 @@ async def create_scheduler_interaction(mode_names: dict[int, str]) -> SigenInter
                 mode_names=mode_names,
                 event_time_utc=datetime.now(timezone.utc),
                 logger=logger,
+                zappi_status=startup_zappi_status,
+                zappi_daily=startup_zappi_daily,
             )
             return sigen
         except Exception as e:

main.py

@@ -111,7 +111,7 @@ def _build_today_forecast_email_sections(
             '<div style="margin-top:12px;padding:10px 12px;background:#f8fafc;'
             'border:1px solid #e4ebf3;border-radius:10px;">'
             '<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;'
-            'color:#5b6b82;margin-bottom:6px;">Today\'s Solar Forecast</div>'
+            'color:#143a52;font-weight:700;margin-bottom:6px;">Today\'s Solar Forecast</div>'
             '<div style="font-size:12px;color:#5b6b82;">Unavailable</div>'
             '</div>'
         )
@@ -164,7 +164,7 @@ def _build_today_forecast_email_sections(
         '<div style="margin-top:12px;padding:10px 12px;background:#f8fafc;'
         'border:1px solid #e4ebf3;border-radius:10px;">'
         '<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;'
-        'color:#5b6b82;margin-bottom:6px;">Today\'s Solar Forecast</div>'
+        'color:#143a52;font-weight:700;margin-bottom:6px;">Today\'s Solar Forecast</div>'
         f'<table role="presentation" style="width:100%;border-collapse:collapse;">{rows_html}</table>'
         '</div>'
     )

notifications/email_notifications.py

@@ -73,6 +73,8 @@ async def notify_startup_email(
     mode_names: dict[int, str],
     event_time_utc: datetime,
     logger: logging.Logger,
+    zappi_status: dict[str, Any] | None = None,
+    zappi_daily: dict[str, Any] | None = None,
 ) -> None:
     """Send a startup email with current mode, SOC, and recent transition summary.
 
@@ -84,6 +86,8 @@ async def notify_startup_email(
         mode_names: Mapping from mode value to human-readable mode label.
         event_time_utc: Startup timestamp in UTC.
         logger: Logger instance used for status/error output.
+        zappi_status: Most recent Zappi live-status snapshot, or None when unavailable.
+        zappi_daily: Today's Zappi daily charge totals, or None when unavailable.
     """
     sender = _get_email_sender_instance()
     if sender is None:
@@ -110,6 +114,7 @@ async def notify_startup_email(
         f"SOC {soc_text} • Solar Today {today_solar_text}"
     )
     forecast_text, forecast_html = _build_today_forecast_email_sections(today_period_forecast)
+    zappi_text, zappi_html = _build_zappi_email_sections(zappi_status, zappi_daily)
 
     now_local = event_time_utc.astimezone(LOCAL_TZ)
     previous_2230 = (now_local - timedelta(days=1)).replace(
@@ -143,7 +148,7 @@ async def notify_startup_email(
         timeline_text = "\n".join(timeline_lines)
         timeline_html = (
             f'<div style="margin-top:12px;padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">'
-            f'<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:6px;">Transitions since 10:30 PM</div>'
+            f'<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:6px;">Transitions since 10:30 PM</div>'
             f'<table role="presentation" style="width:100%;border-collapse:collapse;">{timeline_rows}</table>'
             f'</div>'
         )
@@ -163,7 +168,8 @@ async def notify_startup_email(
         f"Battery SOC: {soc_text}\n\n"
         f"Solar Produced Today: {today_solar_text}\n\n"
         f"{forecast_text}\n"
-        "Transitions Since 10:30 PM\n"
+        + (f"{zappi_text}\n" if zappi_text else "")
+        + "Transitions Since 10:30 PM\n"
         "---------------------------\n"
         f"{timeline_text}\n"
     )
@@ -185,27 +191,28 @@ async def notify_startup_email(
                     <tr>
                         <td style="width:50%;padding:0 6px 0 0;vertical-align:top;">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Current Mode</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Current Mode</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(current_mode_label)}</div>
                             </div>
                         </td>
                         <td style="width:50%;padding:0 0 0 6px;vertical-align:top;">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Battery SOC</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Battery SOC</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(soc_text)}</div>
                             </div>
                         </td>
                     </tr>
                     <tr>
                         <td style="padding:12px 6px 0 0;vertical-align:top;" colspan="2">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Solar Produced Today</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Solar Produced Today</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(today_solar_text)}</div>
                             </div>
                         </td>
                     </tr>
                 </table>
                 {forecast_html}
+                {zappi_html}
                 {timeline_html}
             </div>
         </div>
@@ -271,10 +278,13 @@ def _build_zappi_email_sections(
         total_kwh = zappi_daily.get("total_kwh", 0.0)
         diverted_kwh = zappi_daily.get("diverted_kwh", 0.0)
         boosted_kwh = zappi_daily.get("boosted_kwh", 0.0)
+        grid_imported_kwh = zappi_daily.get("grid_imported_kwh")
         rows_text += [
             f"Today's Total to EV: {total_kwh:.2f} kWh  "
             f"(Solar: {diverted_kwh:.2f} kWh | Grid: {boosted_kwh:.2f} kWh)",
         ]
+        if grid_imported_kwh is not None:
+            rows_text.append(f"Grid Imported Today: {grid_imported_kwh:.2f} kWh")
         rows_html += (
             f'<tr><td style="padding:4px 8px 4px 0;font-size:12px;color:#5b6b82;white-space:nowrap;">Today — Total to EV</td>'
             f'<td style="padding:4px 0;font-size:12px;font-weight:600;color:#172033;">{total_kwh:.2f} kWh</td></tr>'
@@ -283,6 +293,11 @@ def _build_zappi_email_sections(
             f'<tr><td style="padding:4px 8px 4px 0;font-size:12px;color:#5b6b82;white-space:nowrap;">&nbsp;&nbsp;Grid boost</td>'
             f'<td style="padding:4px 0;font-size:12px;color:#172033;">{boosted_kwh:.2f} kWh</td></tr>'
         )
+        if grid_imported_kwh is not None:
+            rows_html += (
+                f'<tr><td style="padding:4px 8px 4px 0;font-size:12px;color:#5b6b82;white-space:nowrap;">Grid Imported Today</td>'
+                f'<td style="padding:4px 0;font-size:12px;font-weight:600;color:#172033;">{grid_imported_kwh:.2f} kWh</td></tr>'
+            )
 
     plain_text = (
         "EV Charger (Zappi)\n"
@@ -294,7 +309,7 @@ def _build_zappi_email_sections(
         '<div style="margin-top:12px;padding:10px 12px;background:#f8fafc;'
         'border:1px solid #e4ebf3;border-radius:10px;">'
         '<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;'
-        'color:#5b6b82;margin-bottom:6px;">EV Charger (Zappi)</div>'
+        'color:#143a52;font-weight:700;margin-bottom:6px;">EV Charger (Zappi)</div>'
         '<table role="presentation" style="width:100%;border-collapse:collapse;">'
         + rows_html
         + '</table>'
@@ -445,7 +460,7 @@ async def notify_mode_change_email(
             )
         timeline_section = (
             f'<div style="margin-top:12px;padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">'
-            f'<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:6px;">'
+            f'<div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:6px;">'
             f'Transitions since 10:30 PM</div>'
             f'<table role="presentation" style="width:100%;border-collapse:collapse;">{timeline_rows}</table>'
             f'</div>'
@@ -470,21 +485,21 @@ async def notify_mode_change_email(
                     <tr>
                         <td style="width:50%;padding:0 6px 0 0;vertical-align:top;">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Time</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Time</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(local_time)}</div>
                             </div>
                         </td>
                         <td style="width:50%;padding:0 0 0 6px;vertical-align:top;">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Battery SOC</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Battery SOC</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(soc_text)}</div>
                             </div>
                         </td>
                     </tr>
                     <tr>
                         <td style="padding:12px 6px 0 0;vertical-align:top;" colspan="2">
                             <div style="padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;">
-                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:3px;">Solar Produced Today</div>
+                                <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:3px;">Solar Produced Today</div>
                                 <div style="font-size:14px;font-weight:700;color:#172033;">{escape(today_solar_text)}</div>
                             </div>
                         </td>
@@ -493,7 +508,7 @@ async def notify_mode_change_email(
                 {forecast_html}
                 {zappi_html}
                 <div style="margin-bottom:12px;padding:10px 12px;background:#f8fafc;border:1px solid #e4ebf3;border-radius:10px;font-size:13px;line-height:1.5;color:#26354d;">
-                    <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#5b6b82;margin-bottom:4px;">Reason</div>
+                    <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.07em;color:#143a52;font-weight:700;margin-bottom:4px;">Reason</div>
                     {escape(reason)}
                 </div>
                 <details style="margin-bottom:0;">

notifications/notification_email_helpers.py

@@ -14,6 +14,7 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 import main
+import logic.mode_change as _mode_change_module
 from logic.mode_change import apply_mode_change
 
 _script_logger = logging.getLogger("test_mode_change_email")
@@ -80,11 +81,11 @@ async def run_test(mode: int, period: str, reason: str, soc: float) -> bool:
         True when simulated apply_mode_change completed successfully.
     """
     mode_names = {value: name for name, value in main.SIGEN_MODES.items()}
-    previous_full_sim = main.FULL_SIMULATION_MODE
+    previous_full_sim = _mode_change_module.FULL_SIMULATION_MODE
 
     try:
         # Force simulation path so the test does not send inverter commands.
-        main.FULL_SIMULATION_MODE = True
+        _mode_change_module.FULL_SIMULATION_MODE = True
         return await apply_mode_change(
             sigen=None,
             mode=mode,
@@ -95,7 +96,7 @@ async def run_test(mode: int, period: str, reason: str, soc: float) -> bool:
             logger=_script_logger,
         )
     finally:
-        main.FULL_SIMULATION_MODE = previous_full_sim
+        _mode_change_module.FULL_SIMULATION_MODE = previous_full_sim
 
 
 def main_cli() -> None:

scripts/test_mode_change_email.py

@@ -193,7 +193,7 @@ async def test_get_daily_totals_empty_history() -> None:
     client.get_daily_history = AsyncMock(return_value=[])
     interaction = ZappiInteraction(client)
     result = await interaction.get_daily_totals(date(2026, 4, 15))
-    assert result == {"total_kwh": 0.0, "diverted_kwh": 0.0, "boosted_kwh": 0.0}
+    assert result == {"total_kwh": 0.0, "diverted_kwh": 0.0, "boosted_kwh": 0.0, "grid_imported_kwh": 0.0}
 
 
 # ---------------------------------------------------------------------------