AI Mail Summary

AI-Powered Mail Summary

The integration generates a grid image (sensor.mail_grid_image_path) that arranges all of today's USPS Informed Delivery mail piece images into a single PNG. This grid can be passed directly to a vision-capable AI model to produce a natural language summary of your mail and packages — identifying senders, describing what's arriving, and summarizing delivery status.

Prerequisites

• The integration must be configured and receiving USPS Informed Delivery emails.
• Allow external image use must be enabled in the integration options so the grid image is saved to the www/ folder and accessible as a media source.
• A vision-capable AI integration must be set up in Home Assistant. The example below uses Google Generative AI (Gemini), but any integration that exposes an ai_task.generate_data entity with image attachment support will work.

How it works

An automation watches for changes to mail and package sensors and fires either when a count changes or at a scheduled morning time. It then:

1. Attaches the grid image to an AI task prompt describing the current delivery status.
2. The AI reads both the image and the structured sensor data to produce a concise summary.
3. The summary is sent as a push notification with the USPS GIF attached.

Automation

alias: Daily Mail AI Summary
description: >
  Natural language mail and package notifications using AI vision.
  Triggers on sensor changes or at 9 AM. Requires Allow external image use
  to be enabled so the grid image is accessible as a media source.
triggers:
  - trigger: state
    entity_id:
      - sensor.mail_packages_delivered
      - sensor.mail_amazon_packages_delivered
      - sensor.mail_fedex_delivered
      - sensor.mail_ups_delivered
      - sensor.mail_usps_mail
      - sensor.mail_packages_in_transit
      - sensor.mail_usps_delivered
      - sensor.mail_walmart_delivered
    id: Mail
    for:
      seconds: 5
  - trigger: time
    at: "09:00:01"
    id: Morning
conditions:
  - condition: or
    conditions:
      - condition: and
        conditions:
          - condition: trigger
            id: Mail
          - condition: template
            value_template: >
              {% set from = trigger.from_state.state %}
              {% set to = trigger.to_state.state %}
              {{ from not in ['unavailable', 'unknown', 'none'] and
                 to not in ['unavailable', 'unknown', 'none'] and
                 (from | int(0)) != (to | int(0)) }}
      - condition: trigger
        id: Morning
  - condition: time
    after: "09:00:00"
  - condition: template
    value_template: >
      {{ states('sensor.mail_grid_image_path') not in ['unavailable', 'unknown', 'none', ''] }}
actions:
  - action: ai_task.generate_data
    data:
      task_name: Generate Daily Mail Summary
      entity_id: ai_task.YOUR_AI_ENTITY  # Replace with your AI task entity
      instructions: >
        The current time is {{ as_timestamp(now()) | timestamp_custom("%I:%M %p on %A %B %d, %Y") }}.

        Trigger type: {{ trigger.id }}
        {% if trigger.id == 'Mail' %}
        {% set sensor_labels = {
          'sensor.mail_fedex_delivered': 'FedEx',
          'sensor.mail_ups_delivered': 'UPS',
          'sensor.mail_amazon_packages_delivered': 'Amazon',
          'sensor.mail_packages_delivered': 'General/USPS',
          'sensor.mail_usps_mail': 'USPS Mail',
          'sensor.mail_packages_in_transit': 'Packages in Transit',
          'sensor.mail_walmart_delivered': 'Walmart'
        } %}
        What changed: {{ sensor_labels.get(trigger.entity_id, trigger.entity_id) }}
        went from {{ trigger.from_state.state }} to {{ trigger.to_state.state }}.
        {% endif %}

        Current status:
        - Mail pieces today: {{ states('sensor.mail_usps_mail') | int(0) }}
        - Packages in transit: {{ states('sensor.mail_packages_in_transit') | int(0) }}
        Delivering today:
        - USPS: {{ states('sensor.mail_usps_delivering') | int(0) }}
        - FedEx: {{ states('sensor.mail_fedex_delivering') | int(0) }}
        - UPS: {{ states('sensor.mail_ups_delivering') | int(0) }}
        - Amazon: {{ states('sensor.mail_amazon_packages') | int(0) }}
        - Walmart: {{ states('sensor.mail_walmart_delivering') | int(0) }}
        Delivered today: {{ states('sensor.mail_packages_delivered') | int(0) }}

        Rules:
        1. Tone based on trigger:
           - Morning: Full day outlook — mail arriving and expected deliveries.
           - Sensor change before 9 AM: Lead with what just changed, then remaining deliveries.
           - Sensor change after 9 AM: Focus on the specific delivery event.
        2. Mail analysis (only before 9 AM): If mail pieces > 0, examine the grid image
           and identify each sender visible on the envelopes. If 0, say no mail is arriving.
        3. Keep responses under 300 characters and 15 words where possible.
           Examples:
           - "Mail from Xfinity and Chase. 3 packages arriving via USPS and FedEx."
           - "Your FedEx package just arrived. 1 UPS package still on the way."
           - "All 3 packages delivered."
      attachments:
        - media_content_id: >
            media-source://media_source/www/mail_and_packages/{{ states('sensor.mail_grid_image_path').split('/')[-1] }}
          media_content_type: image/png
    response_variable: ai_summary
  - action: notify.notify  # Replace with your notification service
    data:
      title: "📬 Today's Mail and Packages"
      message: "{{ ai_summary['data'] }}"
      data:
        attachment:
          url: "{{ states('sensor.mail_image_url') }}"
          hide-thumbnail: false
        apns_headers:
          apns-collapse-id: homeassistant-mail-update
        push:
          thread-id: homeassistant-mail-update
initial_state: true
mode: single

Customization

• entity_id: ai_task.YOUR_AI_ENTITY — Replace with the ai_task.* entity for your AI integration. Find it under Settings → Devices & services → your AI integration → entities.
• notify.notify — Replace with your notification service (e.g. notify.mobile_app_your_phone).
• Carrier list — Remove delivering/delivered lines for carriers you haven't enabled.
• Notification data — The apns_headers and push blocks are for iOS via the Home Assistant Companion App. Remove or replace them for other notification platforms.
• Morning time — Adjust the 09:00:01 trigger and 09:00:00 time condition to match your preferred morning check time.

Sensor reference

Sensor	Description
sensor.mail_grid_image_path	Local filesystem path to today's grid image PNG.
sensor.mail_image_url	Internet-accessible URL to the USPS GIF (requires external image use enabled).
sensor.mail_image_system_path	Local filesystem path to the USPS GIF.