Provided by: spamassassin_4.0.2~rc2-1_all 
NAME
DecodeShortURLs - Check for shortened URLs
SYNOPSIS
loadplugin Mail::SpamAssassin::Plugin::DecodeShortURLs
url_shortener tinyurl.com
url_shortener_get bit.ly
url_shortener_custom_user_agent t.co curl/8.6.0
body HAS_SHORT_URL eval:short_url()
describe HAS_SHORT_URL Message has one or more shortened URLs
body SHORT_URL_REDIR eval:short_url_redir()
describe SHORT_URL_REDIR Message has shortened URL that resulted in a valid redirection
body SHORT_URL_CHAINED eval:short_url_chained()
describe SHORT_URL_CHAINED Message has shortened URL chained to other shorteners
body SHORT_URL_MAXCHAIN eval:short_url_maxchain()
describe SHORT_URL_MAXCHAIN Message has shortened URL that causes too many redirections
body SHORT_URL_LOOP eval:short_url_loop()
describe SHORT_URL_LOOP Message has short URL that loops back to itself
body SHORT_URL_200 eval:short_url_code('200') # Can check any non-redirect HTTP code
describe SHORT_URL_200 Message has shortened URL returning HTTP 200
body SHORT_URL_404 eval:short_url_code('404') # Can check any non-redirect HTTP code
describe SHORT_URL_404 Message has shortened URL returning HTTP 404
uri URI_TINYURL_BLOCKED m,https://tinyurl\.com/app/nospam,
describe URI_TINYURL_BLOCKED Message contains a tinyurl that has been disabled due to abuse
uri URI_BITLY_BLOCKED m,^https://bitly\.com/a/blocked,
describe URI_BITLY_BLOCKED Message contains a bit.ly URL that has been disabled due to abuse
DESCRIPTION
This plugin looks for URLs shortened by a list of URL shortening services. Upon finding a matching URL,
plugin will send a HTTP request to the shortening service and retrieve the Location-header which points
to the actual shortened URL. It then adds this URL to the list of URIs extracted by SpamAssassin which
can then be accessed by uri rules and plugins such as URIDNSBL.
This plugin will follow chained redirections, where a short URL redirects to another short URL.
Redirection depth limit can be set with "max_short_url_redirections".
Maximum of "max_short_urls" short URLs are checked in a message (10 by default). Setting it to 0
disables HTTP requests, allowing only short_url() test to work and report found shorteners.
All supported rule types for checking short URLs and redirection status are documented in SYNOPSIS
section.
NOTES
This plugin runs at priority -10 so that it may modify the parsed URI list prior to normal uri rules or
the URIDNSBL plugin but after the Redirector plugin.
USER SETTINGS
url_shortener domain [domain...] (default: none)
Domains that should be considered as an URL shortener. If the domain begins with a '.', 3rd level
tld of the main domain will be checked.
Example:
url_shortener tinyurl.com
url_shortener .page.link
url_shortener_get domain [domain...] (default: none)
Alias to "url_shortener". HTTP request will be done with GET method, instead of default HEAD.
Required for some services like bit.ly to return blocked URL correctly.
Example:
url_shortener_get bit.ly
url_shortener_custom_user_agent domain user-agent (default: none)
Custom HTTP user-agent to be used for specific domains, instead of the default specified in
"url_shortener_user_agent". Required for some services like t.co to return blocked URL correctly.
Example:
url_shortener_custom_user_agent t.co curl/8.6.0
clear_url_shortener [domain] [domain...]
Clear configured url_shortener and url_shortener_get domains, for example to override default
settings from an update channel. If domains are specified, then only those are removed from list.
PRIVILEGED SETTINGS
url_shortener_cache_type (default: none)
The cache type that is being utilized. Currently only supported value is "dbi" that implies
"url_shortener_cache_dsn" is a DBI connect string. DBI module is required.
Example: url_shortener_cache_type dbi
url_shortener_cache_dsn (default: none)
The DBI dsn of the database to use.
For SQLite, the database will be created automatically if it does not already exist, the supplied
path and file must be read/writable by the user running spamassassin or spamd.
For MySQL/MariaDB or PostgreSQL, see sql-directory for database table creation clauses.
You will 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:
url_shortener_cache_dsn dbi:SQLite:dbname=/var/lib/spamassassin/DecodeShortURLs.db
url_shortener_cache_username (default: none)
The username that should be used to connect to the database. Not used for SQLite.
url_shortener_cache_password (default: none)
The password that should be used to connect to the database. Not used for SQLite.
url_shortener_cache_ttl (default: 86400)
The length of time a cache entry will be valid for in seconds. Default is 86400 (1 day).
See "url_shortener_cache_autoclean" for database cleaning.
ADMINISTRATOR SETTINGS
url_shortener_cache_autoclean (default: 1000)
Automatically purge old entries from database. Value describes a random run chance of 1/x. The
default value of 1000 means that cleaning is run approximately once for every 1000 messages
processed. Value of 1 would mean database is cleaned every time a message is processed.
Set 0 to disable automatic cleaning and to do it manually.
url_shortener_loginfo (default: 0 (off))
If this option is enabled (set to 1), then short URLs and the decoded URLs will be logged with info
priority.
url_shortener_timeout (default: 5)
Maximum time a short URL HTTP request can take, in seconds.
max_short_urls (default: 10)
Maximum amount of short URLs that will be looked up per message. Chained redirections are not
counted, only initial short URLs found.
Setting it to 0 disables HTTP requests, allowing only short_url() test to work and report any found
shortener URLs.
max_short_url_redirections (default: 10)
Maximum depth of chained redirections that a short URL can generate.
url_shortener_user_agent (default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/101.0.4951.67 Safari/537.36)
Set default User-Agent header for HTTP requests. Some services require it to look like a common
browser. User-Agent can be overriden on a per url_shortener basis using the "url_shortener_ua"
setting.
ACKNOWLEDGEMENTS
Original DecodeShortURLs plugin was developed by Steve Freegard.
perl v5.40.1 2025-08-11 Mail::SpamAssa...DecodeShortURLs(3pm)