Module rspamd_task

This module provides routines for tasks manipulation in rspamd. Tasks usually represent messages being scanned, and this API provides access to such elements as headers, symbols, metrics and so on and so forth. Normally, task objects are passed to the lua callbacks allowing to check specific properties of messages and add the corresponding symbols to the scan’s results.

Example:

rspamd_config.DATE_IN_PAST = function(task)
	local dm = task:get_date{format = 'message', gmt = true}
	local dt = task:get_date{format = 'connect', gmt = true}
	-- A day
	if dt - dm > 86400 then
		return true
	end

	return false
end

Brief content:

Functions:

Function Description
rspamd_task.create([cfg]) Create a new empty task.
rspamd_task.load_from_file(filename[, cfg]) Loads a message from specific file.
rspamd_task.load_from_string(message[, cfg]) Loads a message from specific file.

Methods:

Method Description
task:get_message() Returns task raw message content as opaque text.
task:set_message(msg) Updates task message with another message; It also parses a message to.
task:process_message() Parses message.
task:get_cfg() Get configuration object for a task.
task:get_mempool() Returns memory pool valid for a lifetime of task.
task:get_session() Returns asynchronous session object that is used by many rspamd asynchronous.
task:set_session(session) Sets new async session for a task.
task:get_ev_base() Return asynchronous event base for using in callbacks and resolver.
task:get_worker() Returns a worker object associated with the task.
task:insert_result([enforce_symbol,]symbol, weight[, option1, ...]) Insert specific symbol to the tasks scanning results assigning the initial.
task:insert_result_named(shadow_result, [enforce_symbol,]symbol, weight[, option1, ...]) Insert specific symbol to the tasks scanning results assigning the initial.
task:adjust_result(symbol, score[, option1, ...]) Alters the existing symbol’s score to a new score.
task:remove_result(symbol[, shadow_result]) Removes the symbol from a named or unnamed/default result.
task:set_pre_result(action, [message, [module], [score], [priority], [flags]) Sets pre-result for a task.
task:has_pre_result() Returns true if task has some pre-result being set.
task:append_message(message, [category]) Adds a message to scanning output.
task:get_urls([need_emails|list_protos][, need_images]) Get all URLs found in a message.
task:get_urls_filtered([{flags_include}, [{flags_exclude}]], [{protocols_mask}]) Get urls managed by either exclude or include flags list.
task:has_urls([need_emails]) Returns ‘true’ if a task has urls listed.
task:inject_url(url) Inserts an url into a task (useful for redirected urls).
task:get_content() Get raw content for the specified task.
task:get_filename() Returns filename for a specific task.
task:get_rawbody() Get raw body for the specified task.
task:get_emails() Get all email addresses found in a message.
task:get_text_parts() Get all text (and HTML) parts found in a message.
task:get_parts() Get all mime parts found in a message.
task:get_meta_words([how='stem']) Get meta words from task (subject and displayed names).
task:get_request_header(name) Get value of a HTTP request header.
task:set_request_header(name, value) Set value of a HTTP request header.
task:get_subject() Returns task subject (either from the protocol override or from a header).
task:get_header(name[, case_sensitive]) Get decoded value of a header specified with optional case_sensitive flag.
task:has_header(name[, case_sensitive]) Get decoded value of a header specified with optional case_sensitive flag.
task:get_header_raw(name[, case_sensitive]) Get raw value of a header specified with optional case_sensitive flag.
task:get_header_full(name[, case_sensitive[, need_modified]]) Get raw value of a header specified with optional case_sensitive flag.
task:get_header_count(name[, case_sensitive]) Lightweight version if you need just a header’s count.
task:get_raw_headers() Get all undecoded headers of a message as a string.
task:get_headers([need_modified=false]) Get all headers of a message in the same format as get_header_full.
task:modify_header(name, mods) Modify an existing or non-existing header with the name name.
task:get_received_headers() Returns a list of tables of parsed received headers.
task:get_queue_id() Returns queue ID of the message being processed.
task:get_uid() Returns ID of the task being processed.
task:get_resolver() Returns ready to use rspamd_resolver object suitable for making asynchronous DNS requests.
task:set_resolver(resolver) Sets rspamd_resolver for a specified task.
task:inc_dns_req() Increment number of DNS requests for the task.
task:get_dns_req() Get number of dns requests being sent in the task.
task:has_recipients([type]) Return true if there are SMTP or MIME recipients for a task.
task:get_recipients([type]) Return SMTP or MIME recipients for a task.
task:get_principal_recipient() Returns a single string with so called principal recipient for a message.
task:get_reply_sender() Returns a single string with address that should be used to reply on a message.
task:set_recipients([type], {rcpt1, rcpt2...}, [how='add']) Sets recipients for a task.
task:has_from([type]) Return true if there is SMTP or MIME sender for a task.
task:get_from([type]) Return SMTP or MIME sender for a task.
task:set_from(type, addr) Sets sender for a task.
task:get_user() Returns authenticated user name for this task if specified by an MTA.
task:set_user([username]) Sets or resets (if username is not specified) authenticated user name for this task.
task:get_from_ip() Returns rspamd_ip object of a sender that is provided by MTA.
task:set_from_ip(str) Set tasks’s IP address based on the passed string.
task:get_client_ip() Returns rspamd_ip object of a client connected to rspamd (normally, it is an IP address of MTA).
task:get_helo() Returns the value of SMTP helo provided by MTA.
task:get_hostname() Returns the value of sender’s hostname provided by MTA.
task:get_images() Returns list of all images found in a task as a table of rspamd_image.
task:get_archives() Returns list of all archives found in a task as a table of rspamd_archive.
task:get_dkim_results() Returns list of all dkim check results as table of maps.
task:get_symbol(name, [shadow_result_name]) Searches for a symbol name in all metrics results and returns a list of tables.
task:get_symbols_all() Returns array of symbols matched in default metric with all metadata.
task:get_symbols([shadow_result_name]) Returns array of all symbols matched for this task.
task:get_groups([need_private]) Returns a map [group -> group_score] for matched group.
task:get_symbols_numeric() Returns array of all symbols matched for this task.
task:get_symbols_tokens() Returns array of all symbols as statistical tokens.
task:process_ann_tokens(symbols, ann_tokens, offset, [min]) Processes ann tokens.
task:has_symbol(name, [shadow_result_name]) Fast path to check if a specified symbol is in the task’s results.
task:enable_symbol(name) Enable specified symbol for this particular task.
task:disable_symbol(name) Disable specified symbol for this particular task.
task:get_date(type[, gmt]) Returns timestamp for a connection or for a MIME message.
task:get_message_id() Returns message identifier from the Message-ID header.
task:get_timeval([raw]) Returns the timestamp for a task start processing time.
task:get_scan_time([set]) Returns 2 floating point numbers.
task:get_metric_result() Get full result of a metric as a table.
task:get_metric_score(name) Get the current score of metric name (must be nil or ‘default’) .
task:get_metric_action(name) Get the current action of metric name (must be nil or ‘default’).
task:set_metric_score(name, score) Set the current score of metric name.
task:set_metric_subject(subject) Set the subject in the default metric.
task:learn(is_spam[, classifier) Learn classifier classifier with the task.
task:set_settings(obj) Set users settings object for a task.
task:set_settings_id(id) Set users settings id for a task (must be registered previously).
task:get_settings() Gets users settings object for a task.
task:lookup_settings(key) Gets users settings object with the specified key for a task.
task:get_settings_id() Get numeric hash of settings id if specified for this task.
task:set_milter_reply(obj) Set special reply for milter.
task:process_re(params) Processes the specified regexp and returns number of captures (cached or new).
task:cache_set(key, value) Store some value to the task cache.
task:cache_get(key) Returns cached value or nil if nothing is cached.
task:get_size() Returns size of the task in bytes (that includes headers + parts size).
task:set_flag(flag_name[, set]) Set specific flag for task.
task:has_flag(flag_name) Checks for a specific flag in task.
task:get_flags() Get list of flags for task.
task:get_digest() Returns message’s unique digest (32 hex symbols).
task:store_in_file([mode|table]) If task was loaded using file scan, then this method just returns its name,.
task:get_protocol_reply([flags]) This method being called from a postfilter will return reply for a message.
task:headers_foreach(callback, [params]) This method calls callback for each header that satisfies some condition.
task:disable_action(action) Disables some action for this task (e.g.
task:get_newlines_type() Returns the most frequent newlines type met in a task.
task:get_stat_tokens() Returns list of tables the statistical tokens.
task:lookup_words(map, function({o, n, s, f}) ... end) Matches words in a task (including meta words) against some map (set, regexp and so on).
task:get_dns_req() Get number of dns requests being sent in the task.

Functions

The module rspamd_task defines the following functions.

Function rspamd_task.create([cfg])

Create a new empty task

Parameters:

No parameters

Returns:

  • {rspamd_task}: new task

Back to module description.

Function rspamd_task.load_from_file(filename[, cfg])

Loads a message from specific file

Parameters:

No parameters

Returns:

  • {boolean,rspamd_task|error}: status + new task or error message

Back to module description.

Function rspamd_task.load_from_string(message[, cfg])

Loads a message from specific file

Parameters:

No parameters

Returns:

  • {boolean,rspamd_task|error}: status + new task or error message

Back to module description.

Methods

The module rspamd_task defines the following methods.

Method task:get_message()

Returns task raw message content as opaque text

Parameters:

No parameters

Returns:

  • {rspamd_text}: task raw content

Back to module description.

Method task:set_message(msg)

Updates task message with another message; It also parses a message to fill the internal structures. Input might be a string, a lua_text or a table of the former stuff.

Parameters:

  • msg {string/text/table}: new message to set

Returns:

  • {boolean,number}: if a message has been set + its raw size

Back to module description.

Method task:process_message()

Parses message

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_cfg()

Get configuration object for a task.

Parameters:

No parameters

Returns:

  • {rspamd_config}: (config.html)[configuration object] for the task

Back to module description.

Method task:get_mempool()

Returns memory pool valid for a lifetime of task. It is used internally by many rspamd routines.

Parameters:

No parameters

Returns:

  • {rspamd_mempool}: memory pool object

Back to module description.

Method task:get_session()

Returns asynchronous session object that is used by many rspamd asynchronous utilities internally.

Parameters:

No parameters

Returns:

  • {rspamd_session}: session object

Back to module description.

Method task:set_session(session)

Sets new async session for a task

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_ev_base()

Return asynchronous event base for using in callbacks and resolver.

Parameters:

No parameters

Returns:

  • {rspamd_ev_base}: event base

Back to module description.

Method task:get_worker()

Returns a worker object associated with the task

Parameters:

No parameters

Returns:

  • {rspamd_worker}: worker object

Back to module description.

Method task:insert_result([enforce_symbol,]symbol, weight[, option1, ...])

Insert specific symbol to the tasks scanning results assigning the initial weight to it.

Parameters:

  • enforce_symbol {boolean}: if represented and true, then insert symbol even if it is not registered in the metric
  • symbol {string}: symbol to insert
  • weight {number}: initial weight (this weight is multiplied by the metric weight)
  • options {string}: list of optional options attached to a symbol inserted

Returns:

No return

Example:

local function cb(task)
	if task:get_header('Some header') then
		task:insert_result('SOME_HEADER', 1.0, 'Got some header')
	end
end

Back to module description.

Method task:insert_result_named(shadow_result, [enforce_symbol,]symbol, weight[, option1, ...])

Insert specific symbol to the tasks scanning results assigning the initial weight to it.

Parameters:

  • shadow_result {string}: name of shadow result
  • enforce_symbol {boolean}: if represented and true, then insert symbol even if it is not registered in the metric
  • symbol {string}: symbol to insert
  • weight {number}: initial weight (this weight is multiplied by the metric weight)
  • options {string}: list of optional options attached to a symbol inserted

Returns:

No return

Back to module description.

Method task:adjust_result(symbol, score[, option1, ...])

Alters the existing symbol’s score to a new score. It is not affected by metric score or grow factor. You can also add new options using this method. Symbol must be already inserted into metric or an error will be emitted.

Parameters:

  • symbol {string}: symbol to adjust
  • score {number}: this value is NOT multiplied by the metric score
  • options {string/table}: list of optional options attached to a symbol adjusted

Returns:

No return

Back to module description.

Method task:remove_result(symbol[, shadow_result])

Removes the symbol from a named or unnamed/default result

Parameters:

  • symbol {string}: symbol to remove
  • shadow_result {string}: name of shadow result

Returns:

  • {boolean}: true if a symbol has been removed

Back to module description.

Method task:set_pre_result(action, [message, [module], [score], [priority], [flags])

Sets pre-result for a task. It is used in pre-filters to specify early result of the task scanned. If a pre-filter sets some result, then further processing may be skipped. For selecting action it is possible to use global table rspamd_actions or a string value:

  • reject: reject message permanently
  • add header: add spam header
  • rewrite subject: rewrite subject to spam subject
  • greylist: greylist message
  • accept or no action: whitelist message

This function also accepts a table from Rspamd 2.6 with the following keys:

  • action: string required
  • message: string
  • module: string
  • score: number
  • priority: integer
  • flags: flags string
  • result: named result if needed

Parameters:

  • action {rspamd_action or string}: a numeric or string action value
  • message {string}: action message
  • module {string}: optional module name
  • score {number/nil}: optional explicit score
  • priority {number/nil}: optional explicit priority
  • flags {string/nil}: optional flags (e.g. ‘least’ for least action)

Returns:

No return

Example:

local function cb(task)
	local gr = task:get_header('Greylist')
	if gr and gr == 'greylist' then
		task:set_pre_result('soft reject', 'Greylisting required')
	end
end

Back to module description.

Method task:has_pre_result()

Returns true if task has some pre-result being set. If result has been set this function also returns pre result action, message and module as strings in this order.

Parameters:

No parameters

Returns:

  • {boolean,[string,string,string]}: true if task has some pre-result being set

Back to module description.

Method task:append_message(message, [category])

Adds a message to scanning output.

Parameters:

  • message {string}: no description
  • message {category}: category

Returns:

No return

Example:

local function cb(task)
	task:append_message('Example message')
end

Back to module description.

Method task:get_urls([need_emails|list_protos][, need_images])

Get all URLs found in a message. Telephone urls and emails are not included unless explicitly asked in list_protos

Parameters:

  • need_emails {boolean}: if true then return also email urls, this can be a comma separated string of protocols desired or a table (e.g. mailto or telephone)
  • need_images {boolean}: return urls from images (<img src=…>) as well

Returns:

  • {table rspamd_url}: list of all urls found

Example:

local function phishing_cb(task)
	local urls = task:get_urls({'https', 'http'});

	if urls then
		for _,url in ipairs(urls) do
			if url:is_phished() then
				return true
			end
		end
	end
	return false
end

Back to module description.

Method task:get_urls_filtered([{flags_include}, [{flags_exclude}]], [{protocols_mask}])

Get urls managed by either exclude or include flags list

  • If flags include are nil then all but excluded urls are returned
  • If flags exclude are nil then only included explicitly urls are returned
  • If both parameters are nil then all urls are included

Parameters:

  • flags_include {table}: included flags
  • flags_exclude {table}: excluded flags
  • protocols_mask {table}: include only specific protocols

Returns:

  • {table rspamd_url}: list of urls matching conditions

Back to module description.

Method task:has_urls([need_emails])

Returns ‘true’ if a task has urls listed

Parameters:

  • need_emails {boolean}: if true then return also email urls

Returns:

  • {boolean}: true if a task has urls (urls or emails if need_emails is true)

Back to module description.

Method task:inject_url(url)

Inserts an url into a task (useful for redirected urls)

Parameters:

  • url {lua_url}: url to inject

Returns:

No return

Back to module description.

Method task:get_content()

Get raw content for the specified task

Parameters:

No parameters

Returns:

  • {text}: the data contained in the task

Back to module description.

Method task:get_filename()

Returns filename for a specific task

Parameters:

No parameters

Returns:

  • {string|nil}: filename or nil if unknown

Back to module description.

Method task:get_rawbody()

Get raw body for the specified task

Parameters:

No parameters

Returns:

  • {text}: the data contained in the task

Back to module description.

Method task:get_emails()

Get all email addresses found in a message.

Parameters:

No parameters

Returns:

  • {table rspamd_url}: list of all email addresses found

Back to module description.

Method task:get_text_parts()

Get all text (and HTML) parts found in a message

Parameters:

No parameters

Returns:

  • {table rspamd_text_part}: list of text parts

Back to module description.

Method task:get_parts()

Get all mime parts found in a message

Parameters:

No parameters

Returns:

  • {table rspamd_mime_part}: list of mime parts

Back to module description.

Method task:get_meta_words([how='stem'])

Get meta words from task (subject and displayed names)

  • stem: stemmed words (default)
  • norm: normalised words (utf normalised + lowercased)
  • raw: raw words in utf (if possible)
  • full: list of tables, each table has the following fields:
    • [1] - stemmed word
    • [2] - normalised word
    • [3] - raw word
    • [4] - flags (table of strings)

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_request_header(name)

Get value of a HTTP request header.

Parameters:

  • name {string}: name of header to get

Returns:

  • {rspamd_text}: value of an HTTP header

Back to module description.

Method task:set_request_header(name, value)

Set value of a HTTP request header. If value is omitted, then a header is removed

Parameters:

  • name {string}: name of header to get
  • value {rspamd_text/string}: new header’s value

Returns:

No return

Back to module description.

Method task:get_subject()

Returns task subject (either from the protocol override or from a header)

Parameters:

No parameters

Returns:

  • {string}: value of a subject (decoded)

Back to module description.

Method task:get_header(name[, case_sensitive])

Get decoded value of a header specified with optional case_sensitive flag. By default headers are searched in caseless matter.

Parameters:

  • name {string}: name of header to get
  • case_sensitive {boolean}: case sensitiveness flag to search for a header

Returns:

  • {string}: decoded value of a header

Back to module description.

Method task:has_header(name[, case_sensitive])

Get decoded value of a header specified with optional case_sensitive flag. By default headers are searched in the case insensitive matter.

Parameters:

  • name {string}: name of header to get
  • case_sensitive {boolean}: case sensitiveness flag to search for a header

Returns:

  • {boolean}: true if header exists

Back to module description.

Method task:get_header_raw(name[, case_sensitive])

Get raw value of a header specified with optional case_sensitive flag. By default headers are searched in caseless matter.

Parameters:

  • name {string}: name of header to get
  • case_sensitive {boolean}: case sensitiveness flag to search for a header

Returns:

  • {string}: raw value of a header

Back to module description.

Method task:get_header_full(name[, case_sensitive[, need_modified]])

Get raw value of a header specified with optional case_sensitive flag. By default headers are searched in caseless matter. This method returns more information about the header as a list of tables with the following structure:

  • name - name of a header
  • value - raw value of a header
  • decoded - decoded value of a header
  • tab_separated - true if a header and a value are separated by tab character
  • empty_separator - true if there are no separator between a header and a value

Parameters:

  • name {string}: name of header to get
  • case_sensitive {boolean}: case sensitiveness flag to search for a header
  • need_modified {boolean}: return a modified value of a header if presented

Returns:

  • {list of tables}: all values of a header as specified above

Example:

function check_header_delimiter_tab(task, header_name)
	for _,rh in ipairs(task:get_header_full(header_name)) do
		if rh['tab_separated'] then return true end
	end
	return false
end

Back to module description.

Method task:get_header_count(name[, case_sensitive])

Lightweight version if you need just a header’s count

  • By default headers are searched in caseless matter.

Parameters:

  • name {string}: name of header to get
  • case_sensitive {boolean}: case sensitiveness flag to search for a header

Returns:

  • {number}: number of header’s occurrences or 0 if not found

Back to module description.

Method task:get_raw_headers()

Get all undecoded headers of a message as a string

Parameters:

No parameters

Returns:

  • {rspamd_text}: all raw headers for a message as opaque text

Back to module description.

Method task:get_headers([need_modified=false])

Get all headers of a message in the same format as get_header_full

Parameters:

No parameters

Returns:

  • {table of headers data}: all headers for a message

Back to module description.

Method task:modify_header(name, mods)

Modify an existing or non-existing header with the name name Mods is a table with the following structure:

  • { “add” = { {order, value}, {order, value} }, “remove” = {order, order, order}
  • } Modifications are evaluated in order: remove, add, so headers are first removed (if any) and then added Order in remove starts from 1, where 0 means ‘remove all’, and negative value means remove from the end Order in addition means addition from the top: 0 means the most top header, 1 one after, etc negative order means addition to the end, e.g. -1 is appending header.

Parameters:

No parameters

Returns:

  • {bool}: true if header could be modified (always true unless we don’t have an unparsed message)

Back to module description.

Method task:get_received_headers()

Returns a list of tables of parsed received headers. A tables returned have the following structure:

  • from_hostname - string that represents hostname provided by a peer
  • from_ip - string representation of sending IP address
  • real_hostname - hostname as resolved by MTA
  • real_ip - rspamd_ip object representing sending IP address
  • by_hostname - MTA hostname
  • proto - protocol, e.g. ESMTP or ESMTPS
  • timestamp - received timestamp
  • for - for value (unparsed mailbox)

Please note that in some situations rspamd cannot parse all the fields of received headers. In that case you should check all strings for validity.

Parameters:

No parameters

Returns:

  • {table of tables}: list of received headers described above

Back to module description.

Method task:get_queue_id()

Returns queue ID of the message being processed.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_uid()

Returns ID of the task being processed.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_resolver()

Returns ready to use rspamd_resolver object suitable for making asynchronous DNS requests.

Parameters:

No parameters

Returns:

  • {rspamd_resolver}: resolver object associated with the task’s session

Example:

local logger = require "rspamd_logger"

local function task_cb(task)
	local function dns_cb(resolver, to_resolve, results, err)
		-- task object is available due to closure
		task:inc_dns_req()
		if results then
			logger.info(string.format('<%s> [%s] resolved for symbol: %s',
				task:get_message_id(), to_resolve, 'EXAMPLE_SYMBOL'))
			task:insert_result('EXAMPLE_SYMBOL', 1)
		end
	end
	local r = task:get_resolver()
	r:resolve_a(task:get_session(), task:get_mempool(), 'example.com', dns_cb)
end

Back to module description.

Method task:set_resolver(resolver)

Sets rspamd_resolver for a specified task.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:inc_dns_req()

Increment number of DNS requests for the task. Is used just for logging purposes.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_dns_req()

Get number of dns requests being sent in the task

Parameters:

No parameters

Returns:

  • {number}: number of DNS requests

Back to module description.

Method task:has_recipients([type])

Return true if there are SMTP or MIME recipients for a task.

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP recipients and fallback to MIME if failed, 1 or smtp means checking merely SMTP recipients and 2 or mime means MIME recipients only

Returns:

  • {bool,integer}: true if there are recipients of the following type and a number of such a recipients excluding artificial ones

Back to module description.

Method task:get_recipients([type])

Return SMTP or MIME recipients for a task. This function returns list of internet addresses each one is a table with the following structure:

  • name - name of internet address in UTF8, e.g. for Vsevolod Stakhov <blah@foo.com> it returns Vsevolod Stakhov
  • addr - address part of the address
  • user - user part (if present) of the address, e.g. blah
  • domain - domain part (if present), e.g. foo.com

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP recipients and fallback to MIME if failed, 1 or smtp means checking merely SMTP recipients and 2 or mime means MIME recipients only

Returns:

  • {list of addresses}: list of recipients or nil

Back to module description.

Method task:get_principal_recipient()

Returns a single string with so called principal recipient for a message. The order of check is the following:

  • deliver-to request header
  • the first recipient (envelope)
  • the first recipient (mime)

Parameters:

No parameters

Returns:

  • {string}: principal recipient

Back to module description.

Method task:get_reply_sender()

Returns a single string with address that should be used to reply on a message

  • reply-to header
  • from header
  • smtp from as a last resort

Parameters:

No parameters

Returns:

  • {address}: email address

Back to module description.

Method task:set_recipients([type], {rcpt1, rcpt2...}, [how='add'])

Sets recipients for a task. This function accepts table that will be converted to the address. If some fields are missing they are subsequently reconstructed by this function. E.g. if you specify ‘user’ and ‘domain’, then address and raw string will be reconstructed

  • name - name of internet address in UTF8, e.g. for Vsevolod Stakhov <blah@foo.com> it returns Vsevolod Stakhov
  • addr - address part of the address
  • user - user part (if present) of the address, e.g. blah
  • domain - domain part (if present), e.g. foo.com

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP recipients and fallback to MIME if failed, 1 or smtp means checking merely SMTP recipients and 2 or mime means MIME recipients only
  • recipients {list of tables}: recipients to set
  • how {string}: define how to set recipients: rewrite - rewrite existing recipients, alias - treat existing recipients as aliased recipients, add - add new recipients

Returns:

  • {boolean}: result of the operation

Back to module description.

Method task:has_from([type])

Return true if there is SMTP or MIME sender for a task.

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP recipients and fallback to MIME if failed, 1 or smtp means checking merely SMTP recipients and 2 or mime means MIME recipients only

Returns:

  • {bool}: true if there is sender of the following type

Back to module description.

Method task:get_from([type])

Return SMTP or MIME sender for a task. This function returns an internet address which one is a table with the following structure:

  • raw - the original value without any processing
  • name - name of internet address in UTF8, e.g. for Vsevolod Stakhov <blah@foo.com> it returns Vsevolod Stakhov
  • addr - address part of the address
  • user - user part (if present) of the address, e.g. blah
  • domain - domain part (if present), e.g. foo.com
  • flags - table with following keys set to true if given condition fulfilled:
    • [valid] - valid SMTP address in conformity with https://tools.ietf.org/html/rfc5321#section-4.1.
    • [ip] - domain is IPv4/IPv6 address
    • [braced] - angled <blah@foo.com> address
    • [quoted] - quoted user part
    • [empty] - empty address
    • [backslash] - user part contains backslash
    • [8bit] - contains 8bit characters

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP sender and fallback to MIME if failed, 1 or smtp means checking merely SMTP sender and 2 or mime means MIME From: only

Returns:

  • {address}: sender or nil

Back to module description.

Method task:set_from(type, addr)

Sets sender for a task. This function accepts table that will be converted to the address. If some fields are missing they are subsequently reconstructed by this function. E.g. if you specify ‘user’ and ‘domain’, then address and raw string will be reconstructed

  • name - name of internet address in UTF8, e.g. for Vsevolod Stakhov <blah@foo.com> it returns Vsevolod Stakhov
  • addr - address part of the address
  • user - user part (if present) of the address, e.g. blah
  • domain - domain part (if present), e.g. foo.com

Parameters:

  • type {integer|string}: if specified has the following meaning: 0 or any means try SMTP sender and fallback to MIME if failed, 1 or smtp means checking merely SMTP sender and 2 or mime means MIME From: only
  • {table {no type}: no description

Returns:

  • {boolean}: success or not

Back to module description.

Method task:get_user()

Returns authenticated user name for this task if specified by an MTA.

Parameters:

No parameters

Returns:

  • {string}: username or nil

Back to module description.

Method task:set_user([username])

Sets or resets (if username is not specified) authenticated user name for this task.

Parameters:

No parameters

Returns:

  • {string}: the previously set username or nil

Back to module description.

Method task:get_from_ip()

Returns rspamd_ip object of a sender that is provided by MTA

Parameters:

No parameters

Returns:

  • {rspamd_ip}: ip address object

Back to module description.

Method task:set_from_ip(str)

Set tasks’s IP address based on the passed string

Parameters:

  • str {string}: string representation of ip

Returns:

No return

Back to module description.

Method task:get_client_ip()

Returns rspamd_ip object of a client connected to rspamd (normally, it is an IP address of MTA)

Parameters:

No parameters

Returns:

  • {rspamd_ip}: ip address object

Back to module description.

Method task:get_helo()

Returns the value of SMTP helo provided by MTA.

Parameters:

No parameters

Returns:

  • {string}: HELO value

Back to module description.

Method task:get_hostname()

Returns the value of sender’s hostname provided by MTA

Parameters:

No parameters

Returns:

  • {string}: hostname value

Back to module description.

Method task:get_images()

Returns list of all images found in a task as a table of rspamd_image. Each image has the following methods:

  • get_width - return width of an image in pixels
  • get_height - return height of an image in pixels
  • get_type - return string representation of image’s type (e.g. ‘jpeg’)
  • get_filename - return string with image’s file name
  • get_size - return size in bytes

Parameters:

No parameters

Returns:

  • {list of rspamd_image}: images found in a message

Back to module description.

Method task:get_archives()

Returns list of all archives found in a task as a table of rspamd_archive. Each archive has the following methods available:

  • get_files - return list of strings with filenames inside archive
  • get_files_full - return list of tables with all information about files
  • is_encrypted - return true if an archive is encrypted
  • get_type - return string representation of image’s type (e.g. ‘zip’)
  • get_filename - return string with archive’s file name
  • get_size - return size in bytes

Parameters:

No parameters

Returns:

  • {list of rspamd_archive}: archives found in a message

Back to module description.

Method task:get_dkim_results()

Returns list of all dkim check results as table of maps. Callee must ensure that dkim checks have been completed by adding dependency on DKIM_TRACE symbol. Fields in map:

  • result - string result of check:
    • reject
    • allow
    • tempfail
    • permfail
    • not found
    • bad record
  • domain - dkim domain
  • selector - dkim selector
  • bhash - short version of b tag (8 base64 symbols)
  • fail_reason - reason of failure (if applicable)

Parameters:

No parameters

Returns:

  • {list of maps}: dkim check results

Back to module description.

Method task:get_symbol(name, [shadow_result_name])

Searches for a symbol name in all metrics results and returns a list of tables one per metric that describes the symbol inserted. Please note, that for using this function you need to ensure that the symbol being queried is already checked. This is guaranteed if there is a dependency between the caller symbol and the checked symbol (either virtual or real). Please check rspamd_config:register_dependency method for details. The symbols are returned as the list of the following tables:

  • metric - name of metric
  • score - score of a symbol in that metric
  • options - a table of strings representing options of a symbol
  • group - a group of symbol (or ‘ungrouped’)

Parameters:

  • name {string}: symbol’s name

Returns:

  • {list of tables}: list of tables or nil if symbol was not found

Back to module description.

Method task:get_symbols_all()

Returns array of symbols matched in default metric with all metadata

Parameters:

No parameters

Returns:

  • {table}: table of tables formatted as in task:get_symbol() except that metric is absent and name is added

Back to module description.

Method task:get_symbols([shadow_result_name])

Returns array of all symbols matched for this task

Parameters:

No parameters

Returns:

  • {table, table}: table of strings with symbols names + table of theirs scores

Back to module description.

Method task:get_groups([need_private])

Returns a map [group -> group_score] for matched group. If need_private is unspecified, then the global option public_groups_only is used for default.

Parameters:

No parameters

Returns:

  • {table, number}: a map [group -> group_score]

Back to module description.

Method task:get_symbols_numeric()

Returns array of all symbols matched for this task

Parameters:

No parameters

Returns:

  • {table|number, table|number}: table of numbers with symbols ids + table of theirs scores

Back to module description.

Method task:get_symbols_tokens()

Returns array of all symbols as statistical tokens

Parameters:

No parameters

Returns:

  • {table|number}: table of numbers

Back to module description.

Method task:process_ann_tokens(symbols, ann_tokens, offset, [min])

Processes ann tokens

Parameters:

  • symbols {table|string}: list of symbols in this profile
  • ann_tokens {table|number}: list of tokens (including metatokens)
  • offset {integer}: offset for symbols token (#metatokens)
  • min {number}: minimum value for symbols found (e.g. for 0 score symbols)

Returns:

  • nothing

Back to module description.

Method task:has_symbol(name, [shadow_result_name])

Fast path to check if a specified symbol is in the task’s results. Please note, that for using this function you need to ensure that the symbol being queried is already checked. This is guaranteed if there is a dependency between the caller symbol and the checked symbol (either virtual or real). Please check rspamd_config:register_dependency method for details.

Parameters:

  • name {string}: symbol’s name

Returns:

  • {boolean}: true if symbol has been found

Back to module description.

Method task:enable_symbol(name)

Enable specified symbol for this particular task

Parameters:

  • name {string}: symbol’s name

Returns:

  • {boolean}: true if symbol has been found

Back to module description.

Method task:disable_symbol(name)

Disable specified symbol for this particular task

Parameters:

  • name {string}: symbol’s name

Returns:

  • {boolean}: true if symbol has been found

Back to module description.

Method task:get_date(type[, gmt])

Returns timestamp for a connection or for a MIME message. This function can be called with a single table arguments with the following fields:

  • format - a format of date returned:
    • message - returns a mime date as integer (unix timestamp)
    • connect - returns a unix timestamp of a connection to rspamd
  • gmt - returns date in GMT timezone (normal for unix timestamps)

By default this function returns connection time in numeric format.

Parameters:

  • type {string}: date format as described above
  • gmt {boolean}: gmt flag as described above

Returns:

  • {string/number}: date representation according to format

Example:

rspamd_config.DATE_IN_PAST = function(task)
	local dm = task:get_date{format = 'message', gmt = true}
	local dt = task:get_date{format = 'connect', gmt = true}
	-- A day
	if dt - dm > 86400 then
		return true
	end

	return false
end

Back to module description.

Method task:get_message_id()

Returns message identifier from the Message-ID header. Angle brackets (<>) are stripped off if present. If a Message-ID header is missing undef is returned.

Parameters:

No parameters

Returns:

  • {string}: ID of the message

Back to module description.

Method task:get_timeval([raw])

Returns the timestamp for a task start processing time.

Parameters:

  • raw {boolean}: if true then two float numbers are returned: task start timestamp and timeout event timestamp

Returns:

  • {table}: table with fields as described in struct timeval in C

Back to module description.

Method task:get_scan_time([set])

Returns 2 floating point numbers: scan real time and scan virtual time. If set is true, then the finishing time is also set (enabled by default). This function should be normally called on idempotent phase.

Parameters:

No parameters

Returns:

  • {number,number}: real and virtual times in seconds with floating point

Back to module description.

Method task:get_metric_result()

Get full result of a metric as a table:

  • score: current score
  • action: current action as a string
  • nnegative: number of negative rules matched
  • npositive: number of positive rules matched
  • positive_score: total score for positive rules
  • negative_score: total score for negative rules
  • passthrough: set to true if message has a passthrough result

Parameters:

No parameters

Returns:

  • {table}: metric result

Back to module description.

Method task:get_metric_score(name)

Get the current score of metric name (must be nil or ‘default’) . Should be used in idempotent filters only.

Parameters:

  • name {string}: name of a metric

Returns:

  • {number,number}: 2 numbers containing the current score and required score of the metric

Back to module description.

Method task:get_metric_action(name)

Get the current action of metric name (must be nil or ‘default’). Should be used in idempotent filters only.

Parameters:

  • name {string}: name of a metric

Returns:

  • {string}: the current action of the metric as a string

Back to module description.

Method task:set_metric_score(name, score)

Set the current score of metric name. Should be used in post-filters only.

Parameters:

  • name {string}: name of a metric
  • score {number}: the current score of the metric

Returns:

No return

Back to module description.

Method task:set_metric_subject(subject)

Set the subject in the default metric

Parameters:

  • subject {string}: subject to set

Returns:

No return

Back to module description.

Method task:learn(is_spam[, classifier)

Learn classifier classifier with the task. If is_spam is true then message is learnt as spam. Otherwise HAM is learnt. By default, this function learns bayes classifier.

Parameters:

  • is_spam {boolean}: learn spam or ham
  • classifier {string}: classifier’s name

Returns:

  • {boolean}: true if classifier has been learnt successfully

Back to module description.

Method task:set_settings(obj)

Set users settings object for a task. The format of this object is described here.

Parameters:

  • obj {any}: any lua object that corresponds to the settings format

Returns:

No return

Back to module description.

Method task:set_settings_id(id)

Set users settings id for a task (must be registered previously)

Parameters:

  • id {number}: numeric id

Returns:

  • {boolean}: true if settings id has been replaced from the existing one

Available in: 2.0+

Back to module description.

Method task:get_settings()

Gets users settings object for a task. The format of this object is described here.

Parameters:

No parameters

Returns:

  • {lua object}: lua object generated from UCL

Back to module description.

Method task:lookup_settings(key)

Gets users settings object with the specified key for a task.

Parameters:

  • key {string}: key to lookup

Returns:

  • {lua object}: lua object generated from UCL

Back to module description.

Method task:get_settings_id()

Get numeric hash of settings id if specified for this task. 0 is returned otherwise.

Parameters:

No parameters

Returns:

  • {number}: settings-id hash

Back to module description.

Method task:set_milter_reply(obj)

Set special reply for milter

Parameters:

  • obj {any}: any lua object that corresponds to the settings format

Returns:

No return

Example:

task:set_milter_reply({
	add_headers = {['X-Lua'] = 'test'},
	-- 1 is the position of header to remove
	remove_headers = {['DKIM-Signature'] = 1},
})

Back to module description.

Method task:process_re(params)

Processes the specified regexp and returns number of captures (cached or new) Params is the table with the following fields (mandatory fields are marked with *):

  • re* : regular expression object
  • type*: type of regular expression:
    • mime: mime regexp
    • header: header regexp
    • rawheader: raw header expression
    • rawmime: raw mime regexp
    • body: raw body regexp
    • url: url regexp
  • header: for header and rawheader regexp means the name of header
  • strong: case sensitive match for headers

Parameters:

No parameters

Returns:

  • {number}: number of regexp occurrences in the task (limited by 255 so far)

Back to module description.

Method task:cache_set(key, value)

Store some value to the task cache

Parameters:

  • key {string}: key to use
  • value {any}: any value (including functions and tables)

Returns:

No return

Back to module description.

Method task:cache_get(key)

Returns cached value or nil if nothing is cached

Parameters:

  • key {string}: key to use

Returns:

  • {any}: cached value

Back to module description.

Method task:get_size()

Returns size of the task in bytes (that includes headers + parts size)

Parameters:

No parameters

Returns:

  • {number}: size in bytes

Back to module description.

Method task:set_flag(flag_name[, set])

Set specific flag for task:

  • no_log: do not log task summary
  • no_stat: do not include task into scanned stats
  • pass_all: check all filters for task
  • extended_urls: output extended info about urls
  • skip: skip task processing
  • learn_spam: learn message as spam
  • learn_ham: learn message as ham
  • broken_headers: header data is broken for a message

Parameters:

  • flag {string}: to set
  • set {boolean}: set or clear flag (default is set)

Returns:

No return

Example:

--[[
For messages with undefined queue ID (scanned with rspamc or WebUI)
do not include results into statistics and do not log task summary
(it will not appear in the WebUI history as well).
]]--

-- Callback function to set flags
local function no_log_stat_cb(task)
  if not task:get_queue_id() then
    task:set_flag('no_log')
    task:set_flag('no_stat')
  end
end

rspamd_config:register_symbol({
  name = 'LOCAL_NO_LOG_STAT',
  type = 'postfilter',
  callback = no_log_stat_cb
})

Back to module description.

Method task:has_flag(flag_name)

Checks for a specific flag in task:

  • no_log: do not log task summary
  • no_stat: do not include task into scanned stats
  • pass_all: check all filters for task
  • extended_urls: output extended info about urls
  • skip: skip task processing
  • learn_spam: learn message as spam
  • learn_ham: learn message as ham
  • broken_headers: header data is broken for a message

Parameters:

  • flag {string}: to check

Returns:

  • {boolean}: true if flags is set

Back to module description.

Method task:get_flags()

Get list of flags for task:

  • no_log: do not log task summary
  • no_stat: do not include task into scanned stats
  • pass_all: check all filters for task
  • extended_urls: output extended info about urls
  • skip: skip task processing
  • learn_spam: learn message as spam
  • learn_ham: learn message as ham
  • broken_headers: header data is broken for a message
  • milter: task is initiated by milter connection

Parameters:

No parameters

Returns:

  • {array of strings}: table with all flags as strings

Back to module description.

Method task:get_digest()

Returns message’s unique digest (32 hex symbols)

Parameters:

No parameters

Returns:

  • {string}: hex digest

Back to module description.

Method task:store_in_file([mode|table])

If task was loaded using file scan, then this method just returns its name, otherwise, a fresh temporary file is created and its name is returned. Default mode is 0600. To convert lua number to the octal mode you can use the following trick: tonumber("0644", 8). The file is automatically removed when task is destroyed.

If table argument is specified, the following extra fields are allowed:

  • mode: same as mode argument
  • force_new: always create a new file
  • filename: use specific filename instead of a temporary one
  • tmpmask: use specific tempmask, e.g. ‘/tmp/file-XXXXX’, where XXXX will be replaced by some random letters
  • keep: do not remove file after task is processed

Parameters:

  • mode {number}: mode for new file

Returns:

  • {string}: file name with task content

Back to module description.

Method task:get_protocol_reply([flags])

This method being called from a postfilter will return reply for a message as it is returned to a client. This method returns the Lua table corresponding to the UCL object. Flags is a table that specify which information should be there in a reply:

  • basic: basic info, such as message-id
  • metrics: metrics and symbols
  • messages: messages
  • dkim: dkim signature
  • milter: milter control block
  • extra: extra data, such as profiling
  • urls: list of all urls in a message

Parameters:

  • flags {table}: table of flags (default is all flags but urls)

Returns:

  • {table}: ucl object corresponding to the reply

Back to module description.

Method task:headers_foreach(callback, [params])

This method calls callback for each header that satisfies some condition. By default, all headers are iterated unless callback returns true. Nil or false means continue of iterations. Params could be as following:

  • full: header value is full table of all attributes task:get_header_full for details
  • regexp: return headers that satisfies the specified regexp

Parameters:

  • callback {function}: function from header name and header value
  • params {table}: optional parameters

Returns:

No return

Back to module description.

Method task:disable_action(action)

Disables some action for this task (e.g. ‘greylist’)

Parameters:

  • action {string}: action to disable

Returns:

  • {boolean}: true if an action was enabled and is disabled after the method call

Back to module description.

Method task:get_newlines_type()

Returns the most frequent newlines type met in a task

Parameters:

No parameters

Returns:

  • {string}: “cr” for \r, “lf” for \n, “crlf” for \r\n

Back to module description.

Method task:get_stat_tokens()

Returns list of tables the statistical tokens:

  • data: 64 bit number encoded as a string
  • t1: the first token (if any)
  • t2: the second token (if any)
  • win: window index
  • flag: table of strings:
    • text: text token
    • meta: meta token
    • lua: lua meta token
    • exception: exception
    • subject: subject token
    • unigram: unigram token

Parameters:

No parameters

Returns:

  • {table of tables}: no description

Back to module description.

Method task:lookup_words(map, function({o, n, s, f}) ... end)

Matches words in a task (including meta words) against some map (set, regexp and so on) and call the specified function with a table containing 4 values:

  • [1] - stemmed word
  • [2] - normalised word
  • [3] - raw word
  • [4] - flags (table of strings)

Parameters:

No parameters

Returns:

No return

Back to module description.

Method task:get_dns_req()

Get number of dns requests being sent in the task

Parameters:

No parameters

Returns:

  • {number}: number of DNS requests

Back to module description.

Back to top.