⚠ This adapter can crash the system very quickly with the Blockly (own query).
 ⚠ So please read this description carefully.

Back to the README

Summary

• Instance Settings
  • Settings TAB IMAP
  • Settings TAB Icons
  • Settings TAB Oauth2
  • Settings TAB Mailparser
• States
  • States imap.0
  • States imap.0.username
  • States imap.0.username.email.emails_xx
  • States imap.0.username.infos
  • States imap.0.username.remote
  • States imap.0.username.remote.copy
  • States imap.0.username.remote.flag
  • States imap.0.username.remote.html
  • States imap.0.username.remote.move
• Blocklys
  • Blockly - Change Instance settings
  • Blockly - Own query
  • Blockly - Query with instance settings
  • Blockly - Set flags
• Array JSON
  • imap.0.xxx.email.email_xx.attach_json
  • imap.0.xxx.json
  • imap.0.xxx.last_activity_json
  • imap.0.xxx.quality
  • imap.0.xxx.status
  • imap.0.online_history
• Example Javascripts and Blocklys

Instance Settings

Instance settings TAB - Create IMAP`s

Summary

 ⚠ The instance must be activated!!!!

• Activ: Enable IMAP connection
• Host: Host - e.g. imap.gmail.com
• Inbox: Default INBOX - Box to be monitored - Possible selection see imap.0.xxx.remote.change_folder example: INBOX.subfolder (point as separator)
• Port: Port - Default 993
• Username: Username - Instance must be activated!!!
• Password: Password - Instance must be activated!!!
  • gmail login
  • outlook Oauth2 authentication

• max.: Create maximum as States - email_01...email_02... (1-99)
• max. HTML: Maximum number of emails as HTML. Should be greater than max States (1-99)
• TLS: Use TLS-Connection - Default true
• Flags: Flags for the query - Possible flags:

ALL - All messages.
ANSWERED - Messages with the Answered flag set.
DELETED - Messages with the Deleted flag set.
DRAFT - Messages with the Draft flag set.
FLAGGED - Messages with the Flagged flag set.
NEW - Messages that have the Recent flag set but not the Seen flag.
SEEN - Messages that have the Seen flag set.
RECENT - Messages that have the Recent flag set.
OLD - Messages that do not have the Recent flag set. This is functionally equivalent to "!RECENT" (as opposed to "!NEW").
UNANSWERED - Messages that do not have the Answered flag set.
UNDELETED - Messages that do not have the Deleted flag set.
UNDRAFT - Messages that do not have the Draft flag set.
UNFLAGGED - Messages that do not have the Flagged flag set.
UNSEEN - Messages that do not have the Seen flag set.

• Choose icon: Folder icon (upload under TAB CREATE ICON)

• tls Option: Default {"rejectUnauthorized": false}
• auto tls: Set to always to always attempt connection upgrades via STARTTLS, required only if upgrading is required, or never to never attempt upgrading. Default: never For more information

• Att.: In order to fill the HTML field, attachments must also be loaded. Very high RAM consumption!!! Default false
• Mail option: Mailparser-Option (Create under TAB MAILPARSER OPTIONEN)
• Token: Token first create

• max. MEMRSS-Limit: From when the actions listed below should be triggered. Default 400 MB
• Restart: When the MEMRSS limit is reached, the adapter restarts. It is checked every 24 hours.

• Object-ID: When the MEMRSS limit is reached, the selected state is set to true. This must be reset manually. It is checked every 24 hours.

• Send: A message is sent when the MEMRSS limit is reached. A message will then be sent whenever MEMRSS is updated.
  • Instance: e. g. telegram.0,telegram.1,pushover.0
  • Instance User: e. g. Peter,Olaf,Thomas

Instance settings TAB - Create ICONS

Summary

• Icon Name: Name for the icon. Please do not use duplicate names. An error message is output when the adapter starts.
• Upload: Upload icon.

Instance settings TAB - oauth2

Summary

• Name Name
• Client ID Client-ID
• Token Token
• Tenant ID Mandaten-ID

Instance settings TAB - MAILPARSER OPTIONS

Summary

• Name: Name for the Mailparser. Please do not use duplicate names. An error message is output when the adapter starts. There is a detailed description here.
• skip Html To Text: Don’t generate plaintext from HTML.
• max Html Length To Parse: The maximum amount of HTML to parse in bytes. If this is exceeded, only header data is generated.
• skip Image Links: Skip converting CID attachments to data URL images. Images are not converted as base64 which saves huge RAM usage.
• skip Text To Html: Don’t generate HTML from plaintext message.
• skip Text Links: Do not linkify links in plaintext content.

States

State imap.0

Summary

State imap.0.username

Summary

State imap.0.username.email.email_xx

Summary

State imap.0.username.infos

Summary

State imap.0.username.remote

Summary

Folder name

Old folder names can be viewed in the imap.0.xxx.remote.change_folder object

State imap.0.username.remote.copy

Summary

State imap.0.username.remote.flag

Summary

State imap.0.username.remote.html

Summary

State imap.0.username.remote.move

Summary

Blocklys

Blockly - Change IMAP query

Summary

• With this you can set these States.
• See the instance setting for possible flags.
• Select IMAP connection or apply to all.
• Max. 100 emails allowed.

Blockly - IMAP own query

Summary

• DANGER! Here comes all the data such. E.g. attachments. This query can push the RAM or CPU to the limit. If an incorrect criterion is created, this can lead to an iobroker crash!!!
• The data is then delivered as JSON.
• With log outputs, the log file becomes very large. Therefore delete the log outputs again later.
• A variable called result must be created.
• Max. 100 emails allowed.
• Beispiele

Blockly - IMAP query with instance settings

Summary

• Load all data from the IMAP connection and process it yourself. The instance setting is used as the search criterion.
• DANGER! Higher RAM consumption
• The data is then delivered as JSON.
• With log outputs, the log file becomes very large. Therefore delete the log outputs again later.
• A variable called result must be created.
• Example

Blockly - Set IMAP flags

Summary

• Set a flag setFlag=set, addFlag=add or delFlag=delete for an email.
• Select mailbox.
• Select setFlag=set, addFlag=add or delFlag=delete.
• select flag.
• Possible flags in imap.0.xxx.status

Array JSON

Array JSON imap.0.xxx.email.email_xx.attach_json

Summary

[
    {
        "partID": "2",
        "id": "<image001.png@01D9C718.240FAD50>",
        "uid": 86,
        "size": "159762",
        "filename": "image001.png",
        "type": "inline",
        "encoding": "base64"
    },
    {
        "partID": "3",
        "id": "<image002.png@01D9C718.36F8AE30>",
        "uid": 86,
        "size": "1296247",
        "filename": "image002.png",
        "type": "inline",
        "encoding": "base64"
    }
]

Array JSON imap.0.xxx.json

Summary

[
    {
        "id": 1,
        "date": "15.08.2023 15:39:17",
        "from": ["test@luckyskills.de"],
        "from_name": ["Tester"],
        "attach": 0,
        "attach_info": [],
        "to": ["github@luckyskills.de"],
        "to_name": ["Lucky-ESA"],
        "subject": "Test",
        "text": "Am 2023-08-10 12:17, schrieb test@luckyskills.de:\n>>> TEST\n",
        "html": false,
        "textAsHtml": "Am 2023-08-10 12:17, schrieb <a href=\"mailto:test@luckyskills.de\">test@luckyskills.de</a>:<br/>&gt;&gt;&gt; TEST</p>",
        "seqno": 74,
        "uid": 93,
        "size": 1077,
        "flag": "unseen"
    }
]

JSON imap.0.xxx.last_activity_json

Summary

{
    "modseq": "196",
    "flags": ["\\Seen"]
}

JSON imap.0.xxx.quality

Summary

{
    "message": "No Message"
}

Possibilities

0: "0x00 - good",
1: "0x01 - general problem",
2: "0x02 - no connection problem",
16: "0x10 - substitute value from controller",
17: "0x11 - general problem by instance",
18: "0x12 - instance not connected",
32: "0x20 - substitute initial value",
64: "0x40 - substitute value from device or instance",
65: "0x41 - general problem by device",
66: "0x42 - device not connected",
68: "0x44 - device reports error",
128: "0x80 - substitute value from sensor",
129: "0x81 - general problem by sensor",
130: "0x82 - sensor not connected",
132: "0x84 - sensor reports error",

JSON imap.0.xxx.status

Summary

{
    "name": "INBOX",
    "flags": ["\\Answered", "\\Flagged", "\\Deleted", "\\Seen", "\\Draft"],
    "readOnly": false,
    "uidvalidity": 1667682367,
    "uidnext": 94,
    "permFlags": ["\\Answered", "\\Flagged", "\\Deleted", "\\Seen", "\\Draft"],
    "keywords": [],
    "newKeywords": true,
    "persistentUIDs": true,
    "nomodseq": false,
    "seq": 0,
    "time": 0,
    "reason": "",
    "user": "github_luckyskills_de",
    "messages": {
        "total": 74,
        "new": 0
    },
    "highestmodseq": "200"
}

Array JSON imap.0.online_history

Summary

[
    {
        "client": "github_luckyskills_de",
        "time": 1692298599784,
        "status": "Online"
    },
    {
        "client": "github_luckyskills_de",
        "time": 1692298232899,
        "status": "Online"
    }
]

Changelog

WORK IN PROGRESS

• (Lucky-ESA) Admin 7.6.20 required

0.4.0 (2026-05-30)

• (copilot) Adapter requires node.js >= 22 now
• (Lucky-ESA) Description revised
• (Lucky-ESA) Admin 7.8.23 required
• (Lucky-ESA) JS-Controller 7.0.7 required
• (Lucky-ESA) Added meta object for attachments

0.3.0 (2024-12-07)

• (Lucky-ESA) Mailbox folder delete added
• (Lucky-ESA) Mailbox folder create added
• (Lucky-ESA) Change Mailbox Folder name added
• (Lucky-ESA) IMAP package changed
• (Lucky-ESA) Migration to ESLint9

0.2.2 (2024-11-07)

• (Lucky-ESA) New design for settings page added
• (Lucky-ESA) Crash if uid is empty for new emails

0.2.1 (2024-09-16)

• (Lucky-ESA) Update dependencies
• (Lucky-ESA) Changed Log info to debug
• (Lucky-ESA) Fixed blockly setFlag crash

0.2.0 (2024-06-15)

• (Lucky-ESA) Updated Blockly definitions
• (Lucky-ESA) JS-Controller >= 5.0.19 required
• (Lucky-ESA) Admin >=6.13.16 required

License

MIT License

Copyright (c) 2023-2026 Lucky-ESA github@luckyskills.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.