NAME

       Redirectors - Check for redirected URLs

SYNOPSIS

         loadplugin    Mail::SpamAssassin::Plugin::Redirectors

         url_redirector bing.com

         body HAS_REDIR_URL          eval:redir_url()
         describe HAS_REDIR_URL      Message has one or more redirected URLs

         body REDIR_URL_CHAINED      eval:redir_url_chained()
         describe REDIR_URL_CHAINED  Message has redirected URL chained to other redirectors

         body REDIR_URL_CHAINED_DOM      eval:redir_url_chained_domain()
         describe REDIR_URL_CHAINED_DOM  Message has redirected URL chained to another redirector on the same domain

         body REDIR_URL_MAXCHAIN     eval:redir_url_maxchain()
         describe REDIR_URL_MAXCHAIN Message has redirected URL that causes too many redirections

         body REDIR_URL_LOOP         eval:redir_url_loop()
         describe REDIR_URL_LOOP     Message has redirected URL that loops back to itself

         body REDIR_URL_404          eval:redir_url_code('404') # Can check any non-redirect HTTP code
         describe REDIR_URL_404      Message has redirected URL returning HTTP 404

DESCRIPTION

       This plugin looks for URLs redirected by a list of URL redirector services.  Upon finding a matching URL,
       plugin will send a HTTP request to the redirector service and retrieve the Location-header which points
       to the actual redirected 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 redirected URL redirects to another redirector.
       Redirection depth limit can be set with "max_redir_url_redirections".

       Maximum of "max_redir_urls" redirected URLs are checked in a message (10 by default).  Setting it to 0
       disables HTTP requests, allowing only redir_url() test to work and report found redirectors.

       All supported rule types for checking redirector URLs and redirection status are documented in SYNOPSIS
       section.

NOTES

       This plugin runs before priority 0 so that it may modify the parsed URI list prior to normal uri rules or
       the URIDNSBL plugin.  It should run before DecodeShortURLs plugin so that redirected short uris are also
       checked.

USER SETTINGS

       url_redirector  domain [domain...]     (default: none)
           Domains  that  should be considered as an URL redirector.  If the domain begins with a '.', 3rd level
           tld of the main domain will be checked.  The 3rd level starting with www with always be  checked  for
           every 2tld.

           Example:

            url_redirector bing.com
            url_redirector .sendgrid.com

       clear_url_redirector  [domain] [domain...]
           Clear  configured  url_redirector  domains,  for  example to override default settings from an update
           channel.  If domains are specified, then only those are removed from list.

       url_redirector_get  domain [domain...]     (default: none)
           Domains that should be considered as an URL redirector.  If the domain begins with a '.',  3rd  level
           tld of the main domain will be checked.  The http GET method will be used to check those domains.

       url_redirector_params regexp (default:
       (?:adurl|af_web_dp|cm_destination|continue|destination|destURL|h|l|login|location|p1|pval|r|redir|redirect|redirectTo|return|returnUrl|referer|service|target|tid|u|url)=(.*))
           Regexp  used  to  parse  uri parameters in order to detect redirectors and to get redirected domains.
           The regexp must match only the redirected domain.

PRIVILEGED SETTINGS

       url_redirector_cache_type     (default: none)
           The cache type that is being  utilized.   Currently  only  supported  value  is  "dbi"  that  implies
           "url_redirector_cache_dsn" is a DBI connect string.  DBI module is required.

           Example: url_redirector_cache_type dbi

       url_redirector_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_redirector_cache_dsn dbi:SQLite:dbname=/var/lib/spamassassin/Redirectors.db

       url_redirector_cache_username  (default: none)
           The username that should be used to connect to the database.  Not used for SQLite.

       url_redirector_cache_password  (default: none)
           The password that should be used to connect to the database.  Not used for SQLite.

       url_redirector_cache_ttl      (default: 86400)
           The length of time a cache entry will be valid for in seconds.  Default is 86400 (1 day).

           See "url_redirector_cache_autoclean" for database cleaning.

ADMINISTRATOR SETTINGS

       url_redirector_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_redirector_loginfo           (default: 0 (off))
           If  this  option is enabled (set to 1), then redirected URLs and the decoded URLs will be logged with
           info priority.

       url_redirector_timeout     (default: 5)
           Maximum time a redirection URL HTTP request can take, in seconds.

       max_redir_urls                 (default: 10)
           Maximum amount of redirector URLs that will be looked up per message.  Chained redirections  are  not
           counted, only initial redirection URLs found.

           Setting  it  to 0 disables HTTP requests, allowing only redir_url() test to work and report any found
           redirector URLs.

       max_redir_url_redirections     (default: 10)
           Maximum depth of chained redirections that a redirector can generate.

       url_redirector_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 User-Agent header for HTTP requests.  Some services require it to look like a common browser.

perl v5.40.1                                       2025-08-11              Mail::SpamAssa...in::Redirectors(3pm)