betool

Documentation

Email

Inbound email (IMAP) and outbound. Thread preservation, attachment parsing.

The email channel ingests your inbound emails and lets a pipeline reply, forward, or create downstream tasks.

Model

Two complementary modules:

  • email_inbound — reception (IMAP)
  • email_outbound — sending (configured operator, or relay via your SMTP)

They are independent: you can use only the inbound module (to triage without replying), or only the outbound module (to send notifications from a pipeline triggered another way).

Setup

  1. Settings → Services → Email, Accounts tab — connect an IMAP mailbox with its credentials.
  2. Map the mailbox to a target pipeline.
  3. (Optional) Configure a sender (SMTP) to reply.

For architectures that need to retain control of their mail servers, betool does not replace your MTA: we read and write via standard IMAP / SMTP.

What the pipeline receives

For each inbound email, a new exchange is created with:

  • exchange.user_message — email body (HTML → normalized text)
  • exchange.email.subject — subject line
  • exchange.email.from — normalized sender
  • exchange.email.thread_id — thread identifier (useful for multi-turn context)
  • exchange.email.attachments — list of FileMetadata (parsed attachments)

Attachments

Attachments can be passed to the file_transform node: selectable text from a PDF (pdf_extract_text, no OCR — a scanned PDF yields no text), reading an Excel workbook as rows (xlsx_to_json, xls_to_json), splitting a PDF or rendering it as images, extracting an archive. From there, your agent can work with them as text or structured data.

Threads & multi-turn context

When a customer replies to a previous response, betool recognizes the thread_id and restores the thread history in the agent's context. This is transparent to pipeline design.

Address quality and bounces

Three nodes protect your sender reputation:

  • email_check — checks one or more addresses before sending: the organization's suppression list, syntax, then the domain's DNS (MX, or failing that A/AAAA; a "null MX" counts as a refusal). It also flags, without changing the verdict, disposable addresses, generic mailboxes (info@…) and risks (typo on a major provider, duplicated extension, "catch-all" server). It blocks nothing itself: it publishes the verdicts and the list of deliverable addresses. No SMTP probe is performed.
  • email_list_clean — qualifies an entire list (for example from an imported file) into three sheets: clean, to review, rejected, ready to export with data_to_file. Deduplication, the same checks as email_check, and analysis of the address's shape. Billed in credits per distinct address, balance checked before processing.
  • email_bounce_parse — reads a non-delivery report received in an inbound mailbox. Addresses are only taken from the report's structured fields, never from the free text. They are added to the suppression list: a permanent failure blocks from the first occurrence; a temporary failure blocks after 3 occurrences, for 72 hours.

Subsequent sends (email_outbound node and email.send tool) automatically remove suppressed addresses; if no recipient remains, nothing is sent. Only an administrator can lift a permanent block.

Known limitations

  • No native MS Exchange EWS support (you can expose Exchange over IMAP).
  • Office 365 ingestion goes through IMAP, not the Microsoft Graph API. (To send from a Microsoft mailbox via Graph, use the microsoft_send_mail node.)
  • Parsing very old emails (nested Outlook 2003 RTF) may lose some formatting.