Mail::...actText(3pm)

🎀 NAME 🎀

okay bestie, welcome to ExtractText — this one literally extracts text from documents. that's it, that's the whole vibe. (the page header calls it Mail::...actText(3pm) btw, don't @ me, the title got truncated, it's giving mysterious 💅)

---

✨ SYNOPSIS ✨

loadplugin Mail::SpamAssassin::Plugin::ExtractText

ifplugin Mail::SpamAssassin::Plugin::ExtractText

  extracttext_external  pdftotext  /usr/bin/pdftotext -nopgbrk -layout -enc UTF-8 {} -
  extracttext_use       pdftotext  .pdf application/pdf

  # http://docx2txt.sourceforge.net
  extracttext_external  docx2txt   /usr/bin/docx2txt {} -
  extracttext_use       docx2txt   .docx application/docx

  extracttext_external  antiword   /usr/bin/antiword -t -w 0 -m UTF-8.txt {}
  extracttext_use       antiword   .doc application/(?:vnd\.?)?ms-?word.*

  extracttext_external  unrtf      /usr/bin/unrtf --nopict {}
  extracttext_use       unrtf      .doc .rtf application/rtf text/rtf

  extracttext_external  odt2txt    /usr/bin/odt2txt --encoding=UTF-8 {}
  extracttext_use       odt2txt    .odt .ott application/.*?opendocument.*text
  extracttext_use       odt2txt    .sdw .stw application/(?:x-)?soffice application/(?:x-)?starwriter

  extracttext_external  tesseract  {OMP_THREAD_LIMIT=1} /usr/bin/tesseract -c page_separator= {} -
  extracttext_use       tesseract  .jpg .png .bmp .tif .tiff image/(?:jpeg|png|x-ms-bmp|tiff)

  # QR-code decoder
  extracttext_external  zbar       /usr/bin/zbarimg -q -D {}
  extracttext_use       zbar       .jpg .png .pdf image/(?:jpeg|png) application/pdf

  add_header   all          ExtractText-Flags _EXTRACTTEXTFLAGS_
  header       PDF_NO_TEXT  X-ExtractText-Flags =~ /\bpdftotext_NoText\b/
  describe     PDF_NO_TEXT  PDF without text
  score        PDF_NO_TEXT  0.001

  header       DOC_NO_TEXT  X-ExtractText-Flags =~ /\b(?:antiword|openxml|unrtf|odt2txt)_NoText\b/
  describe     DOC_NO_TEXT  Document without text
  score        DOC_NO_TEXT  0.001

  header       EXTRACTTEXT  exists:X-ExtractText-Flags
  describe     EXTRACTTEXT  Email processed by extracttext plugin
  score        EXTRACTTEXT  0.001

endif

---

🌸 DESCRIPTION 🌸

so like 🌸 this module rolls up with external tools to pull text out of message parts, and then it sets that text as the rendered part. the external tool must spit out plain text — not HTML, not any other non-textual nonsense. we don't do HTML here, periodt.

how the text gets extracted is completely configurable, and it's all decided by the MIME part type and the file name. slay. 💅

---

👑 CONFIGURATION 👑

heads up bestie: all configuration lines sitting in user_prefs files will be ignored. like, straight up not listened to. sorry. 🙈

• extracttext_maxparts (default: 10) — sets the max mime parts number to analyze. a value of 0 means all mime parts get analyzed. go wild.
• extracttext_timeout (default: 5 10) — sets the timeout in seconds for external tool checks, per attachment.

the second argument specifies the maximum total time for all the checks.

🔧 Tools

extracttext_use

tells you what tool to use for what message parts.

the general syntax is:

extracttext_use  "name"  "specifiers"

• name — the internal name of a tool.
• specifiers — file extension and regular expressions for file names and MIME types. the regular expressions are anchored to beginning and end.

Examples

extracttext_use  antiword  .doc application/(?:vnd\.?)?ms-?word.*
extracttext_use  openxml   .docx .dotx .dotm application/(?:vnd\.?)openxml.*?word.*
extracttext_use  openxml   .doc .dot application/(?:vnd\.?)?ms-?word.*
extracttext_use  unrtf     .doc .rtf application/rtf text/rtf

extracttext_external

defines an external tool. the tool has to read a document from standard input or from a file, and write text to standard output.

the special keyword {} gets substituted at runtime with the temporary filename that the external tool is gonna scan. so cute, so useful. ✨

environment variables can be defined with {KEY=VALUE} — those strings get removed from the commandline.

it is required that the commandline used outputs its result directly to STDOUT. no sidequests, no temp files, straight to STDOUT. 😤

the general syntax is:

extracttext_external "name" "command" "parameters"

• name — the internal name of this tool.
• command — the full path to the external command to run.
• parameters — parameters for the external command. the temporary file name containing the document will be automatically added as the last parameter. automatic queen behavior. 💅

Examples

extracttext_external  antiword  /usr/bin/antiword -t -w 0 -m UTF-8.txt {} -
extracttext_external  unrtf     /usr/bin/unrtf --nopict {}
extracttext_external  odt2txt   /usr/bin/odt2txt --encoding=UTF-8 {}

🦋 Metadata

the plugin adds some pseudo headers to the message. these headers are seen by the bayes system, and can be used in normal SpamAssassin rules. 🔥

the headers are also available as template tags as noted below.

Example

the fictional example headers below are based on a message containing this:

1 A perfectly normal PDF.
2 An OpenXML document with a word document inside. Neither Office
document contains text.

Headers

• X-ExtractText-Chars

Tag: _EXTRACTTEXTCHARS_

contains a count of characters that were extracted.

X-ExtractText-Chars: 10970

• X-ExtractText-Words

Tag: _EXTRACTTEXTWORDS_

contains a count of "words" that were extracted.

X-ExtractText-Chars: 1599

• X-ExtractText-Tools

Tag: _EXTRACTTEXTTOOLS_

contains chains of tools used for extraction.

X-ExtractText-Tools: pdftotext openxml_antiword

• X-ExtractText-Types

Tag: _EXTRACTTEXTTYPES_

contains chains of MIME types for parts found during extraction.

X-ExtractText-Types: application/pdf;
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/ms-word

• X-ExtractText-Extensions

Tag: _EXTRACTTEXTEXTENSIONS_

contains chains of canonicalized file extensions for parts found during extraction.

X-ExtractText-Extensions: pdf docx

• X-ExtractText-Flags

Tag: _EXTRACTTEXTFLAGS_

contains notes from the plugin.

X-ExtractText-Flags: openxml_NoText

• X-ExtractText-Uris

Tag: _EXTRACTTEXTURIS_

contains uris extracted from the plugin.

X-ExtractText-Uris: https://spamassassin.apache.org

Rules

Example:

header    PDF_NO_TEXT  X-ExtractText-Flags =~ /\bpdftotext_Notext\b/
describe  PDF_NO_TEXT  PDF without text

---

💖 ADMINISTRATOR SETTINGS 💖

• extracttext_cache_type (default: none) — the cache type that is being utilized. currently the only supported value is "dbi", which implies "extracttext_cache_dsn" is a DBI connect string. the DBI module is required. 😭

Example: extracttext_cache_type dbi

• extracttext_cache_dsn (default: none) — the DBI dsn of the database to use.

for SQLite, the database gets created automatically if it doesn't already exist, and the supplied path and file must be read/writable by the user running spamassassin or spamd.

for MySQL/MariaDB or PostgreSQL, go look at sql-directory for the database table creation clauses.

you'll need to have the proper DBI module for your database. for example DBD::SQLite, DBD::mysql, DBD::MariaDB or DBD::Pg.

minimum required SQLite version is 3.24.0 (available from DBD::SQLite 1.59_01).

Examples:

extracttext_cache_dsn dbi:SQLite:dbname=/var/lib/spamassassin/ExtractText.db

• extracttext_cache_username (default: none) — the username that should be used to connect to the database. not used for SQLite.
• extracttext_cache_password (default: none) — the password that should be used to connect to the database. not used for SQLite.
• extracttext_cache_ttl (default: 86400) — the length of time a cache entry will be valid for, in seconds. default is 86400 (1 day). 🕐

see "extracttext_cache_autoclean" for database cleaning.

• extracttext_cache_autoclean (default: 1000) — automatically purge old entries from the database. the value describes a random run chance of 1/x. the default value of 1000 means cleaning runs approximately once for every 1000 messages processed. a value of 1 would mean the database is cleaned every single time a message is processed. (iconic but also unhinged, ngl.)

set 0 to disable automatic cleaning and do it manually like a control freak. 💅

---

that's the whole page bestie, you ate 🫶 — this one came from the perl v5.40.1 docs, dated 2026-07-23, filed under Mail::...actText(3pm). go forth and extract some text ✨🦋