smart-mailbox.yaml

blueprint:
  name: 📬 Smart mailbox (Contact Sensor)
  description: >
    # 📬 Smart mailbox using a contact (opening) sensor by @0xAmit
    
    This Blueprint detects mail deposits and collections in your mailbox using a **contact sensor**,
    confirmation entities, and optional counters or datetime entities.
    
    ## ✨ Key features
     - Use a **mail counter** ([Create a counter](https://my.home-assistant.io/redirect/config_flow_start?domain=counter)) to track the number of mails in the mailbox.
     - Record the **date and time** ([Create an input_datetime](https://my.home-assistant.io/redirect/config_flow_start?domain=input_datetime)) of the last mail deposit and collection with datetime entities.
     - Trigger **custom actions** for deposits or collections.

    ## 🎬 Scenarios
    
    <details>
    <summary><b>See details...</b></summary>
    
    
    ### 📭 Mail collection
    
    The user opens the mailbox door (triggering the contact sensor). The configured timeout provides enough time 
    for the automation to check if any mail collection confirmation sensors (e.g., a door sensor or a switch) were 
    triggered within that period.

    #### Scenario A
    
    The user opens the mailbox **first**, then enters their home, triggering the door sensor or a switch.
    
    #### Scenario B
    
    The user exits their home (triggering the door sensor or a switch) **first**, then opens the mailbox.

    In both cases, the timeout allows the automation to determine that this activity is most likely a **collection** rather than a deposit.

    ### 📬 Mail deposit
    
    When mail is deposited, the mailbox sensor changes state (detecting an open/close). If no confirmation entities 
    (e.g., door or window sensors, switches) are activated during the timeout period, the automation classifies 
    this as a **deposit**.
    </details>
    
  domain: automation
  author: Eroak (modified for contact sensors)
  homeassistant:
    min_version: 2024.6.0
    
  input:
  
    detection:
      name: Detection configuration*
      icon: mdi:eye-check
      input:
        mailbox_sensor:
          name: 📬 Mailbox contact sensor
          description: The contact sensor on the mailbox that detects when the mailbox is opened or closed.
          selector:
            entity:
              filter:
                domain: binary_sensor
                device_class:
                  - opening

    collection:
      name: Collection detection settings*
      description: >
        These parameters allow you to configure which entities and within what timeframe the verification 
        will confirm that it is a collection (rather than a mail deposit).
      icon: mdi:call-split
      input:
        timeout_in_seconds:
          name: ⏲️ Timeout delay
          description: >
            The delay (in seconds) after the mailbox sensor is triggered to determine if it was a deposit or a collection.
          default: 45
          selector:
            number:
              min: 0
              max: 120
              step: 5
              unit_of_measurement: "seconds"
              mode: slider
        
        collection_confirming_entities:
          name: ⏻ Entities confirming collection
          description: >
            List of entities (e.g., door or window sensors, switches) that trigger an event during the configured 
            timeout period, helping to confirm if the mailbox sensor activity corresponds to a mail collection.
          selector:
            entity:
              multiple: true
              filter:
                domain:
                  - binary_sensor
                  - switch
                device_class:
                  - door
                  - window

    indicators:
      name: Counter and datetimes indicators (optional)
      icon: mdi:clipboard-text-clock-outline
      collapsed: true
      description: >
        Count and save the date of the last deposit or collection.
            
      input:
        mailbox_counter:
          name: 🔢 Mail counter (optional)
          description: >
            A counter entity to track the number of mails in the mailbox.
          default: ""
          selector:
            entity:
              domain: counter
        
        last_deposit_input_datetime:
          name: 📅 Last deposit datetime (optional)
          description: >
            An entity to store the date and time of the last mail deposit.
          default: ""
          selector:
            entity:
              domain: input_datetime
        
        last_collect_input_datetime:
          name: 📅 Last collection datetime (optional)
          description: >
            An entity to store the date and time of the last mail collection.
          default: ""
          selector:
            entity:
              domain: input_datetime

    actions:
      name: Custom actions (optional)
      description: >
        These actions will be executed right after the timeout period has elapsed, 
        once the automation determines whether it is a collection or a deposit.
      icon: mdi:checkbox-marked-circle-auto-outline
      collapsed: true
      input:
        actions_in:
          name: 📬 Actions after mail deposit (optional)
          description: >
            Actions to execute after a mail deposit is detected.
          default: []
          selector:
            action: {}
        
        actions_out:
          name: 📭 Actions after mail collection (optional)
          description: >
            Actions to execute after a mail collection is detected.
          default: []
          selector:
            action: {}

mode: single

trigger:
  - platform: state
    entity_id: !input mailbox_sensor
    from: "off"
    to: "on"

variables:
  scriptTriggeredAt: "{{ as_timestamp(now()) }}"
  timeoutInSeconds: !input timeout_in_seconds
  collectionConfirmingEntities: !input collection_confirming_entities
  mailboxCounter: !input mailbox_counter
  lastDepositInputDatetime: !input last_deposit_input_datetime
  lastCollectInputDatetime: !input last_collect_input_datetime
  actionsIn: !input actions_in
  actionsOut: !input actions_out

action:
  - alias: "Wait before determining if it's a deposit or collection"
    delay: "{{ timeoutInSeconds }}"

  - if:
      - alias: "Check if no collection entities triggered within timeout"
        condition: template
        value_template: >-
          {% set result = namespace(allDurationsExceedTimeout = true) %}
          {% for sensor in collectionConfirmingEntities %}
              {% if result.allDurationsExceedTimeout %}
                  {%- set delta = ((scriptTriggeredAt - as_timestamp(states[sensor].last_changed)) | round | abs) -%}
                  {% set result.allDurationsExceedTimeout = delta > timeoutInSeconds %}
              {% endif %}
          {% endfor %}
          {{ result.allDurationsExceedTimeout }}
    then:
      - alias: "Mail deposited"
        parallel:
          - alias: "Increment mail counter if set"
            choose:
              - conditions:
                  - condition: template
                    value_template: "{{ mailboxCounter != '' }}"
                sequence:
                  - service: counter.increment
                    target:
                      entity_id: "{{ mailboxCounter }}"
          - alias: "Set last deposit datetime if set"
            choose:
              - conditions:
                  - condition: template
                    value_template: "{{ lastDepositInputDatetime != '' }}"
                sequence:
                  - service: input_datetime.set_datetime
                    target:
                      entity_id: "{{ lastDepositInputDatetime }}"
                    data:
                      timestamp: "{{ scriptTriggeredAt }}"
          - alias: "Trigger actions for deposit"
            default: !input actions_in
    else:
      - alias: "Mail collected"
        parallel:
          - alias: "Reset mail counter if set"
            choose:
              - conditions:
                  - condition: template
                    value_template: "{{ mailboxCounter != '' }}"
                sequence:
                  - service: counter.reset
                    target:
                      entity_id: "{{ mailboxCounter }}"
          - alias: "Set last collection datetime if set"
            choose:
              - conditions:
                  - condition: template
                    value_template: "{{ lastCollectInputDatetime != '' }}"
                sequence:
                  - service: input_datetime.set_datetime
                    target:
                      entity_id: "{{ lastCollectInputDatetime }}"
                    data:
                      timestamp: "{{ scriptTriggeredAt }}"
          - alias: "Trigger actions for collection"
            default: !input actions_out