Add IMAP services for post-processing events (#32107)

* Add IMAP services for post-processing events

* Phrasing and correct typo

* Tiny tweaks

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

source/_integrations/imap.markdown

@@ -160,6 +160,8 @@ template:
       - name: imap_content
         state: "{{ trigger.event.data['subject'] }}"
         attributes:
+          Entry: "{{ trigger.event.data['entry_id'] }}"
+          UID: "{{ trigger.event.data['uid'] }}"
           Message: "{{ trigger.event.data['text'] }}"
           Server: "{{ trigger.event.data['server'] }}"
           Username: "{{ trigger.event.data['username'] }}"
@@ -177,6 +179,50 @@ template:
 
 {% endraw %}
 
+### Services for post-processing
+
+The IMAP integration has some services for post-pressing email messages. The services are intended to be used in automations as actions after an "imap_content" event. The services take the IMAP `entry_id` and the `uid` of the message's event data. You can use a template for the `entry_id` and the `uid`. When the service is set up as a trigger action, you can easily select the correct entry from the UI. You will find the `entry_id` in YAML mode. It is highly recommended you filter the events by the `entry_id`.
+
+Available services are:
+
+- `seen`: Mark the message as seen.
+- `move`: Move the message to a `target_folder` and optionally mark the message `seen`.
+- `delete`: Delete the message.
+
+<div class='note warning'>
+
+When these services are used in an automation, make sure the right triggers and filtering are set up. When messages are deleted, they cannot be recovered. When multiple IMAP entries are set up, make sure the messages are filtered by the `entry_id` as well to ensure the correct messages are processed. Do not use these services unless you know what you are doing.
+
+</div>
+
+## Example - post-processing
+
+The example below filters the event trigger by `entry_id` and marks the message in the event as seen. The `seen` service `entry_id` can be a template or literal string. In UI mode you can select the desired entry from a list as well.
+
+{% raw %}
+
+```yaml
+alias: imap seen example
+description: Mark in incoming message as seen
+trigger:
+  - platform: event
+    event_type: imap_content
+    event_data:
+      entry_id: 91fadb3617c5a3ea692aeb62d92aa869
+condition:
+  - condition: template
+    value_template: "{{ trigger.event.data['sender'] == 'info@example.com' }}"
+action:
+  - service: imap.seen
+    metadata: {}
+    data:
+      entry: "{{ trigger.event.data['entry_id'] }}"
+      uid: "{{ trigger.event.data['uid'] }}"
+mode: single
+```
+
+{% endraw %}
+
 ## Example - keyword spotting
 
 The following example shows the usage of the IMAP email content sensor to scan the subject of an email for text, in this case, an email from the APC SmartConnect service, which tells whether the UPS is running on battery or not.