=======================================================================
  monotomic.json — Field-by-Field Guide
=======================================================================

Each section below mirrors the structure of monotomic.json. Open both
files side by side and use this guide to understand what every field
does, what values it accepts, and how to enable each feature.


-----------------------------------------------------------------------
  SMTP — outgoing mail server credentials
-----------------------------------------------------------------------
smtp[]                          Array of SMTP servers. Add multiple
                                entries to enable bulk SMTP rotation
                                (see configurations.agent.bulk_smtp).

smtp[].host                     SMTP hostname.   e.g. smtp.gmail.com
smtp[].port                     SMTP port.       e.g. 25, 587, 2525, 465
smtp[].secure                   true for 465 (SSL), false for STARTTLS
                                (25 / 587 / 2525)
smtp[].user                     SMTP username.   e.g. your-email@gmail.com
smtp[].pass                     SMTP password
                                Never commit live SMTP credentials. The
                                default monotomic.json uses placeholders and
                                the sender refuses placeholder SMTP credentials
                                when SMTP sending is enabled.


-----------------------------------------------------------------------
  EXTERNAL FILE PATHS — text files loaded at runtime
-----------------------------------------------------------------------
smtps_list.path                 Bulk SMTP rotation list (one per line).
                                Formats:
                                host
                                host|port
                                host|port|user
                                host|port|user|password
                                host:port
                                host:port:user:password
                                smtp://user:password@host:587
                                smtps://user:password@host:465
                                host|port|user|password|from@domain.com
                                host|port|user|password|from1@domain.com,from2@domain.com
                                Legacy: host|port|user|password=from1@domain.com,from2@domain.com
                                IP addresses and printer/no-auth SMTP relays
                                are supported. Missing port defaults to 25
                                when no user is provided, or 587 when a user
                                is provided. Port 465 defaults to secure TLS.
socks_list.path                 SOCKS5 proxies for rotate_ip
proxy_engine_list.path          Bulk SOCKS proxy list path for
                                proxy_socks_direct_engine. Points to
                                proxy_engine.txt.
                                Format:  host:port  or
                                         host:port:user:pass
links_list.path                 Multiple-links pool — one URL per line
froms_list.path                 Multiple from_names pool
emails_list.path                Recipients list — one email per line
senders_list.path               Multiple sender addresses pool
subjects_list.path              Multiple subjects pool — one per line
messages_body.path              HTML body of the outgoing email
messages_to_image_body.path     HTML that gets rendered to an inline
                                image (used by message_to_image)


-----------------------------------------------------------------------
  OUTER ATTACHMENTS — files attached to the outgoing mail
-----------------------------------------------------------------------
attachments[].filename          The name the recipient sees
attachments[].path              Local file or HTML template path
attachments[].active            true = attach, false = skip
                                .zip files are supported as static binary
                                attachments and are delivered as
                                application/zip.
attachments[].display_file_extension
                                true  = keep .ext visible to recipient
                                false = hide the .ext (MIME still tells
                                        the mail client what it is)
attachments[].html_to_svg_config
                                Optional for .svg attachments. HTML in the
                                source file is sanitized and wrapped into a
                                static SVG using width/height/padding/
                                background/title/url_link_enabled/url_link/
                                url_link_text. The configured URL renders only
                                when url_link_enabled is true.
                                Script/event handlers and script-style URLs
                                are stripped before delivery.
attachments[].html_to_wav_config
                                Optional for .wav attachments whose path is
                                an HTML source file. Readable text is extracted
                                and converted into audio/wav using voice/rate/
                                volume/url_link_enabled/url_link/url_link_text
                                when the platform speech backend is available,
                                with a safe fallback WAV generator.
attachments[].html_to_mov_config
                                Optional for .mov attachments whose path is
                                an HTML source file. The HTML is rendered to
                                frames with Puppeteer and encoded to QuickTime
                                MOV with ffmpeg. Supports width/height/fps/
                                duration_seconds/max_frames/quality/
                                ffmpeg_path/codec/pixel_format/background/
                                url_link_enabled/url_link/url_link_text.
configurations.agent.html_conversion_url_link_enabled
                                Shared URL-link switch for all message_to_*
                                HTML conversions. When true, appends
                                html_conversion_url_link using
                                html_conversion_url_link_text before PDF/DOC/
                                RTF/EPUB/XLSX/PPTX/ICS/WAV/MOV conversion.
configurations.agent.embedded_file
                                true = attach inline image(s). Use
                                embedded_file_path for one image or
                                embedded_file_paths for many images. The
                                placeholders [[-EMBEDDED_URL-]],
                                [[-EMBEDDED_URL(2)-]], etc. resolve to unique
                                cid: URLs so multiple images do not collide.

Encryption / obfuscation / scripter (only apply to text-based
attachments — not to binaries like PDF/DOCX/XLSX/EPUB/PPTX/ICS/WAV/MOV,
and not to SVG, which is kept static after sanitization):

attachments[].obfuscate           true/false — wrap visible links to
                                  disguise the destination
attachments[].obfuscate_preset    preset1 | preset2 | preset3 | preset4
                                  preset5 | preset6 | preset7 | preset8
                                  preset9 | preset10
attachments[].encrypted           true/false — apply content encryption
attachments[].encrypted_preset    preset1 | preset2 | preset3 | preset4
                                  preset5 | preset6 | preset7 | preset8
                                  preset9 | preset10
attachments[].scripter            true/false — inject JS obfuscation
attachments[].scripter_preset     preset1 | preset2 | preset3 | preset4
                                  preset5 | preset6 | preset7 | preset8
                                  preset9 | preset10

Special "message_to_*" entries (HTML → real binary on the fly). Turn a
conversion on by setting that attachment entry's active=true. Each entry now
keeps its own conversion settings beside the filename/path:

Message-to-PDF-1.pdf   ←  pdf_config
Message-to-DOC-1.docx  ←  doc_config
Message-to-RTF-1.rtf   ←  rtf_config
Message-to-EPUB-1.epub ←  epub_config
Message-to-XLSX-1.xlsx ←  xlsx_config
Message-to-PPTX-1.pptx ←  pptx_config
invite.ics             ←  message_to_ics_config
Message-to-WAV-1.wav   ←  message_to_wav_config
Message-to-MOV-1.mov   ←  message_to_mov_config


-----------------------------------------------------------------------
  configurations.system — low-level runtime flags
-----------------------------------------------------------------------
turbo_mode                      true = fire emails concurrently per
                                chunk (faster, less ordered)
proxy_socks_direct_engine       Use SOCKS-only direct-MX transport. Requires
                                proxy_engine.proxy_host/proxy_port when
                                multiple_proxy_engine=false. Uses
                                proxy_engine.txt when multiple_proxy_engine=true.
                                Ignores smtp[] credentials, validates proxies,
                                and supports all prepared attachments.
use_zimbra_smtp                 Use the legitimate Zimbra SOAP fallback when
                                normal SMTP submission fails for a Zimbra host.
                                Supports host or full SOAP URL values and
                                tries safe endpoint candidates such as
                                mail./webmail./zimbra.<domain>. Explicit
                                endpoints can be supplied with ZIMBRA_SOAP_HOSTS
                                (comma/semicolon separated). Tuning env vars:
                                  ZIMBRA_AUTH_TIMEOUT_MS
                                  ZIMBRA_SEND_TIMEOUT_MS
                                  ZIMBRA_RETRY_MAX_ATTEMPTS
                                  ZIMBRA_RETRY_BACKOFF_MS
                                  ZIMBRA_MAX_MIME_BYTES
                                  ZIMBRA_SOAP_CANDIDATE_LIMIT
use_exchange_smtp               Use Microsoft EWS adapter
use_free_sending                Use the free/direct MX transport
message_encryption              false by default. When true, encrypts the
                                fully-rendered messages.html body after all
                                placeholders are interpreted, using a
                                self-contained HTML decoder so the original
                                body renders back correctly.
retry_again                     Retry failed sends:
                                  false  = off
                                  true   = 1 retry
                                  N (e.g. 3) = N retries
live_view                       Render a live progress UI in terminal
live_view_theme                 Theme number 1–12
delay_sending                   true = throttle between recipients
delay_sending_seconds           Seconds of pause when delay_sending=true


-----------------------------------------------------------------------
  configurations.message — per-mail envelope and headers
-----------------------------------------------------------------------
from_name                       Display name on the "From:" header
from_email                      Sender address (must match SMTP unless
                                spoofing)
bulk-from_mail                  true = enable the bulk From mail feature.
                                Uses bulk-from-mail.txt and rotates values
                                across SMTPs when bulk_smtp=true.
mail_subject                    Subject line (supports placeholders
                                like [[-RECIPIENT-]])
reply_to                        Optional "Reply-To:" header
mail_priority                   low | normal | high
cc                              Optional CC addresses (comma-separated)
use_bcc                         true = use BCC instead of To: for the
                                recipient
use_attachment                  Master switch for all attachments
use_hide_from_email             Hide the from_email from recipient


-----------------------------------------------------------------------
  configurations.agent — campaign-level feature switches
-----------------------------------------------------------------------
is_multi_thread                 Run multiple sender threads in parallel
how_many_thread                 Thread count when is_multi_thread=true
obfuscator                      Replace your real link with a disguise
obfuscator_link                 The disguised destination URL
qr_code                         Attach a generated QR code image
qr_code_link                    URL encoded inside the QR
qr_code_colors                  "foreground,background" in hex.
                                e.g. "#000000,#FFFFFF"
bulk_smtp                       Rotate through every smtp[] entry for every
                                recipient attempt. In bulk mode the SMTP list
                                is treated as a loop and keeps cycling until
                                the recipient list finishes or you cancel the
                                run. Failed recipients are requeued onto the
                                next SMTP indefinitely by default; set
                                MAX_BULK_SMTP_REQUEUE to a number only if you
                                want an explicit retry cap.
multiple_senders                Rotate through senders.txt
multiple_subjects               Rotate through subjects.txt
multiple_links                  Rotate through links.txt
multiple_proxy_engine           true = load many proxies from proxy_engine.txt
                                and rotate them across sends. false = use the
                                single top-level proxy_engine config.
multiple_from_names             Rotate through froms.txt
message_to_image                Render messages-img.html as an image
                                and embed it inline
message_to_image_link           URL the rendered image links to
embedded_file                   Inline-embed a file in the HTML body
embedded_file_path              Path to the file to embed inline
embedded_file_paths             Array of inline image paths. Use
                                [[-EMBEDDED_URL-]] for the first image and
                                [[-EMBEDDED_URL(2)-]] for the second.
zip_attachment                  true = attach ZIP files from zip_file_path or
                                zip_file_paths. false = skip ZIP attachments.
zip_file_path                   Single .zip attachment path.
zip_file_paths                  Array of .zip attachment paths. Each path may
                                use placeholders and is attached once.
HTML conversion attachments     All active HTML conversion attachment
                                templates can be enabled together. The sender
                                materializes PDF/DOC/RTF/EPUB/XLSX/PPTX/ICS/
                                WAV/MOV in one shared pass, then appends other
                                enabled attachment types such as image, QR,
                                embedded file, and EML.
rotate_ip                       Route delivery through active SOCKS proxies
                                from socks.txt. Supports host:port and
                                host:port:user:pass, validates proxies before
                                sending, then rotates evenly through all good
                                entries.
proxy_engine                    Single-proxy config fields:
                                  proxy_host, proxy_port, protocol,
                                  session_rotation, proxy_username,
                                  proxy_password, smtp_mode, smtp_host,
                                  smtp_port, smtp_secure, smtp_username,
                                  smtp_password, batch_route.
                                batch_route:
                                  recipient_mx      = default. Resolve each
                                                      recipient MX and dial it
                                                      through the SOCKS proxy.
                                  configured_smtp   = use smtp_host/smtp_port/
                                                      smtp_secure and optional
                                                      smtp_username/password
                                                      through the SOCKS proxy.
                                smtp_mode accepts proxy_engine/recipient_mx
                                for default mode, or smtp/smtp_relay/
                                configured_smtp for configured SMTP relay.
                                session_rotation:
                                  per_message       = rotate for each send
                                  sticky_success    = keep a working proxy
                                                      until a send fails, then
                                                      rotate to another one.
                                Startup validation checks SOCKS reachability
                                against configured SMTP when configured_smtp
                                mode is selected. In recipient_mx mode it
                                samples recipient MX hosts and keeps only
                                proxies that can open an SMTP route. Valid
                                proxies are ordered by measured route latency
                                and startup logs include pass/fail counts plus
                                fastest/slowest latency.
                                Runtime failover retries another validated
                                proxy for the same recipient before giving up.
                                Repeatedly failing proxies are removed from the
                                active runtime pool after the failure threshold.
                                Tuning:
                                  PROXY_ENGINE_MX_PROBE_SAMPLE
                                  PROXY_ENGINE_MAX_PROXY_ATTEMPTS
                                  PROXY_ENGINE_PROXY_FAIL_THRESHOLD
proxy_engine.txt                Dedicated bulk proxy list for the SOCKS direct
                                engine. Used only when multiple_proxy_engine=true.
                                Use one proxy per line:
                                  host:port
                                  host:port:user:pass
                                  host:port:socks4
                                  host:port:socks5:user:pass
                                  host|port|user|pass
                                  socks5://user:pass@host:port
                                  socks4://host:port
                                When multiple_proxy_engine=true, these proxies
                                are validated and rotated per send.

  -- HTML → PDF conversion --
attachments[].pdf_config        PDF generation settings stored directly on
                                the Message-to-PDF attachment entry.
pdf_orientation                 portrait | landscape

  -- HTML → DOCX conversion --
attachments[].doc_config        Word generation settings stored directly on
                                the Message-to-DOC attachment entry.
message_to_doc_ahref            Anchor text shown in the document
message_to_doc_ahref_styles     Inline style for the anchor
                                e.g. "font_face: 'Arial', font_size: 15,
                                      bold: true, underline: true"
message_to_doc_link             Destination URL the anchor points to

  -- HTML → RTF conversion --
attachments[].rtf_config        RTF generation settings stored directly on
                                the Message-to-RTF attachment entry.

  -- HTML → EPUB conversion --
attachments[].epub_config       EPUB generation settings stored directly on
                                the Message-to-EPUB attachment entry.
message_to_epub_title           EPUB metadata: title
message_to_epub_author          EPUB metadata: author
message_to_epub_publisher       EPUB metadata: publisher
message_to_epub_content_title   Title of the first chapter

  -- HTML → XLSX conversion --
attachments[].xlsx_config       Excel generation settings stored directly on
                                the Message-to-XLSX attachment entry.

  -- HTML → PPTX conversion --
attachments[].pptx_config       PowerPoint generation settings stored
                                directly on the Message-to-PPTX attachment.
message_to_pptx_title           PPTX metadata: title
message_to_pptx_author          PPTX metadata: author

  -- HTML → ICS (calendar invite) conversion --
attachments[].message_to_ics_config
                                Full RFC 5545 event description stored on the
                                invite.ics attachment entry:

  event_title                   SUMMARY field
  start                         Start datetime
                                e.g. "2026-06-01 09:00"
                                     (UTC unless timezone set)
  end                           End datetime — same format as start
  location                      LOCATION (free text or address)
  description                   Plain-text DESCRIPTION
  timezone                      IANA timezone
                                e.g. "Europe/London", "America/New_York"
  status                        CONFIRMED | TENTATIVE | CANCELLED
  transparency                  OPAQUE (busy) | TRANSPARENT (free)
  priority                      0 (undef) … 9 (lowest), 1 is highest
  organizer_email               Mailbox of the event organizer
  attendees                     ["a@x.com", "b@y.com"] — ATTENDEE list
  alarm_minutes_before          VALARM lead time in minutes;
                                0 = no alarm
  categories                    Comma-separated CATEGORIES
  event_url                     RFC 5545 URL property
  url_link                      Extra link rendered into description
                                + X-ALT-DESC
  url_link_text                 Anchor text for url_link in the HTML
                                alt-description
  rrule                         RFC 5545 RRULE
                                e.g. "FREQ=WEEKLY;BYDAY=MO"

  -- HTML → WAV audio conversion --
attachments[].message_to_wav_config
                                voice/rate/volume settings stored on the WAV
                                attachment entry.

  -- HTML → MOV video conversion --
attachments[].message_to_mov_config
                                width, height, fps, duration_seconds,
                                max_frames, quality, ffmpeg_path, codec,
                                pixel_format, background
                                Requires FFmpeg in PATH or ffmpeg_path.


-----------------------------------------------------------------------
  props.eml_config — builds the .eml file when eml_attachment=true
-----------------------------------------------------------------------
from_name                       From: name inside the .eml
from_email                      From: address inside the .eml
mail_subject                    Subject of the .eml
reply_to                        Reply-To inside the .eml
eml_attachment                  true = attach an .eml file built from this
                                props.eml_config block
eml_attachment_name             Filename for the generated .eml
messages_body.path              HTML body for the .eml

The block below mirrors agent.message_to_* knobs so EML-nested
conversions can override the outer settings per-EML. Empty fields
fall back to the outer agent config.

pdf_orientation                 PDF orientation for the EML-nested PDF
message_to_doc_ahref            Anchor text for the EML-nested DOCX
message_to_doc_ahref_styles     Anchor style for the EML-nested DOCX
message_to_doc_link             Destination URL for the EML-nested DOCX
message_to_epub_title           EPUB title for the EML-nested EPUB
message_to_epub_author          EPUB author
message_to_epub_publisher       EPUB publisher
message_to_epub_content_title   EPUB first-chapter title
message_to_pptx_title           PPTX title for the EML-nested PPTX
message_to_pptx_author          PPTX author
message_to_ics_config           ICS config for the EML-nested ICS
                                (same fields as the outer ICS config)
message_to_wav_config           WAV config for the EML-nested WAV
message_to_mov_config           MOV config for the EML-nested MOV

Each entry in eml_config.attachments has the same shape as the outer
attachments — see "OUTER ATTACHMENTS" above. The HTML-conversion
entries (Message-to-PDF-1.pdf, Message-to-DOC-1.docx, …) live in
props/eml/attachments_msgs/e_messages-<type>.html and are auto-rendered
into real binaries when their active=true.


-----------------------------------------------------------------------
  props.sorter_config
-----------------------------------------------------------------------
options.path                    Path to sorter rules. The file format
                                is one rule per line:
                                  filename.txt|["mx-pattern", "..."]
                                See _init/props/sorter/sorter-options.txt
                                for examples.
                                The sorter streams emails.txt, writes buckets
                                incrementally, caches MX lookups by domain, and
                                places transient lookup failures in
                                Unresolved.txt for retry.
                                Each run writes summary.json with bucket counts,
                                totals, output path, and DNS cache statistics.
                                Domains with no MX records are written to
                                otherNoMX.txt. Domains with MX records that
                                do not match any configured sorter rule are
                                written to OthersMX.txt.
                                Large-run tuning env vars:
                                  SORTER_MX_CONCURRENCY
                                  SORTER_MS_CONCURRENCY
                                  SORTER_DNS_TIMEOUT_MS
                                  SORTER_HTTP_TIMEOUT_MS
                                  SORTER_RETRIES
                                  SORTER_MX_CACHE_LIMIT
                                  SORTER_MAX_OPEN_BUCKETS


-----------------------------------------------------------------------
  verifier
-----------------------------------------------------------------------
verify                          Streams emails.txt and writes valid,
                                invalid, and unresolved files under
                                results/verified/<timestamp>/.
                                Each run writes summary.json with totals, bucket
                                counts, output path, and MX DNS cache statistics
                                when the verifier uses MX/domain checks.
                                HTTP account checks: Microsoft, Google,
                                Hotmail, NetEase.
                                MX/domain checks: Turbify, AliMail,
                                263xmail, BizQQ, Barracuda.
                                Large-run tuning env vars:
                                  VERIFIER_CONCURRENCY
                                  VERIFIER_MX_CONCURRENCY
                                  VERIFIER_HTTP_TIMEOUT_MS
                                  VERIFIER_DNS_TIMEOUT_MS
                                  VERIFIER_RETRIES
                                  VERIFIER_MX_CACHE_LIMIT


=======================================================================
  TIP: monotomic.json may contain // line comments and /* block */
  comments — the CLI strips them before parsing. But many global
  installs and third-party tools do strict JSON.parse, so for
  maximum compatibility keep monotomic.json strict and put your
  notes in this monotomic.help.txt file instead.
=======================================================================
