Add basic instructions to spam-status special scenario.

[racke]

Not a lot of information, but gives a clue how to use the Spam status in your scenario. Found the second snippet in very old resources on the internet.

[dverdin]

Hi @racke ,
Yes, it's the way it works. Than, you also need other operations to make it work.
I'll dig through my training documents to give my own input.
Regards,

[ikedas]

It would be better to write about possible "actions" spam_status scenario may return: spam, ham or unsure.

I'll write if I notice anything more.

[dverdin]

I would add the following introduction (feel free to rephrase if needed):

The spam_status scenario has a very specific behaviour: it is not used to grant authorizations on actions, it only tags messages with the three following status: ham, spam or unsure.

To use it, you will need to know what headers your antispam adds to messages, and how you can interpret them to categorize "ham" (legitimate message), "spam" (high probability that the message is a spam) and "unsure" (the antispam found clues but not enough to categorize it as spam).

For example, let's say that:

• for a ham, no header is added
• for a spam, the antispam adds the header X-Spam-Status: yes
• the antispam adds the header X-Spam-Level: ***..., where most of the time, below 4 "*", it is unsure whether the message is a spam or not.

You could have the following scenario:

title.gettext test x-spam-status  header

match([header->X-Spam-Status][-1],/^\s*yes/)	smtp,dkim,smime,md5  -> spam
match([header->X-Spam-Level][-1],/\*{5,}/)  	        smtp,dkim,smime,md5  -> spam
match([header->X-Spam-Level][-1],/\*{0,4}/) 	        smtp,dkim,smime,md5  -> unsure
true()					       	                        smtp,dkim,md5,smime   -> ham

You have now set rules to tag messages according to their probability to be spam.

Afterwards, you can use the spam-status rule in your send scenarios, as follows. The value of [msg->spam_status] is the one computed by the spam_status scenario according to the antispam headers.

(switch to your documentation)

(I would add the following remark, too, maybe at the end:)

One can legitimately wonder why not use the rules of the spam_status scenario directly in the send scenario. It would lead to the same outcome int terms of moderation or rejection.
It is because Sympa behaviour changes significantly according to the spam_status to protect people in charge of moderation.

A message tagged as spam using the spam_status:

• is not forwarded along with the moderation notice,
• appears with a little dustbin next to its title in the list of messages to be moderated in the web interface to warn moderators.

[dverdin]

Question: I prepared a modification the .md file on your PR branch. Shall I commit directly to your branhc or make a PR? That''s as PR on your PR, so it feels weird...

[racke]

PR on PR is fine.

[dverdin]

PR on PR done. Yo dawg.

[dcaillibaud]

Some more explanations about how is triggered the scenario spam_status.x-spam-status could be welcomed ;-)
(I guess that setting in global or robot configuration a line spam_status foo implies sympa to search for a spam_status.foo scenario)

[dverdin]

Well, it works like any other scenario: the name of the scenario file is composed of the name of the parameter and its value inf the configuration:

parameter.value

I can add it as a remark as the scenario is disconcerting. At least to specify that this parameter can be set in sympa.conf and robot.conf only.
However, we must add that this evaluation always_ takes place for any incoming message.
The only way to skip it is to make a voluntary error in the config file, I guess: pointing a scenario that does not exist. But then you will fill your logs with missing scenario errors.

[dverdin]

I updated my PR on the PR with your remarks.
Note that the lnk to the spam_status parameter won't work in the markdown file, as the parameter definition URL is completely computed from the parameter definition in the Sympa code. Consequently, it is not present in the documentation sources.
You can read it here: https://sympa-community.github.io/gpldoc/man/sympa_config.5.html#spam_status
Thanks @dcaillibaud!

[ikedas]

Note
In the next release (perhaps 6.2.72), scenarios for several spam filters will be bundled in.
See sympa-community/sympa#1470