Skip to content

Docs / All tools / Loop III: Assistant

mail.read_watch

Fetch messages that arrived since the last check.

2 credits. Per call.

Example prompt

Send this to your AI app when Heelo is connected:

Tell me when a new email arrives

Input fields

FieldTypeDescription
account_handlestringWhich configured mailbox to watch.
folderstringFolder to watch for new mail.
cursorstringOpaque cursor from the previous call. Optional: without it the watch resumes from the position saved by the last call for this mailbox, and only when there is none does it establish a baseline (returning no messages that first time).
timeout_sintegerSeconds to wait for new mail before returning empty (max 300).
resetbooleanDiscard the saved position and start a new baseline from now.
end_user_idstringOptional end-user scope.

Output fields

The fields in data when status is success.

FieldType
accountobject
providerstring
folderstring
countinteger
messagesarray of object
next_cursorstring
rebuiltboolean
baseline_establishedboolean
resumed_fromstring
waited_sinteger
untrustedboolean

Code

The call with the input fields that the tool needs. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/mail.read_watch/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {}},
    timeout=120,
)
response.raise_for_status()
print(response.json())