Actions (GNU Mailutils Manual)

5.7 Actions

There are two groups of GNU Sieve actions: built-in actions, which are defined within the library, and external actions, i.e. loadable modules that can be linked in at run time using the require statement (see Require Statement).

5.7.1 Built-in Actions

The GNU libmu_sieve supports the following built-in actions:

stop
keep
discard
fileinto
reject
redirect

Among them the first three actions do not need to be explicitly required by a require statement, while the others do.

These actions are described in detail below.

Action: stop: The stop action ends all processing. If no actions have been executed, then the keep action is taken.

Action: keep: The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed.

Action: discard

Discard silently throws away the current message. No notification is returned to the sender, the message is deleted from the mailbox.

Example:

if header :contains ["from"] ["idiot@example.edu"]
  {
    discard;
  }

Action: fileinto [:permissions mode] folder

Required arguments:

folder: A string representing the folder name

Tagged arguments:

:permissions mode: Specifies the permissions to use, if the mailbox is created.

The fileinto action delivers the message into the specified folder. If the folder is local, it is created using permissions ‘0600’, for regular files, and ‘0700’ for directories. This default can be changed by using the :permissions tag. Its argument is a mode specification, similar to that used by chmod shell utility. It is a list of permissions settings separated by commas. Each setting begins with one of the following letters:

g: Set permissions for the users in the file group.
o: Set permissions for users not in the file’s group.

This letter must be followed by either ‘+’ or ‘=’ and the list of permissions to be set. This latter list is a string containing any one or both of the following characters:

r: Grant permission to read.
w: Grant permission to write.

For example, the following instruction creates the mailbox ~/shared which will be world readable and writable for the group:

  fileinto :permissions "g=rw,o=r" "~/shared"

Notice that:

The :permissions setting are affected by the current umask value.
Only r and w permissions can be set, since other permissions do not seem to be useful for mailboxes. However, for mailboxes that have a directory structure (such as maildir and MH), any settings in ‘g’ and ‘o’ sets imply setting the executable bit.
Owner’s permissions cannot be set. The owner always has all permissions on the mailbox he created.
The :permissions settings apply only to local mailboxes. They are ignored for remote mailboxes.

Action: reject reason

The optional reject action refuses delivery of a message by sending back a message delivery notification to the sender. It resends the message to the sender, wrapping it in a “reject” form, noting that it was rejected by the recipient. The required argument reason is a string specifying the reason for rejecting the message.

Example:

If the message contained

Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you

I've got some great birdseed over here at my place.
Want to buy it?

and the user’s script contained:

if header :contains "from" "coyote@desert.example.org"
  {
    reject "I am not taking mail from you, and I don't want
            your birdseed, either!";
  }

then the original sender <coyote@desert.example.org> would receive the following notification:

To: <coyote@desert.example.org>
X-Authentication-Warning: roadrunner set sender using -f flag
Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
MIME-Version: 1.0
----- =_aaaaaaaaaa0
The original message was received at
Tue, 1 Apr 1997 09:07:15 -0800 from
coyote@desert.example.org.
Message was refused by recipient's mail filtering program.
Reason given was as follows:

I am not taking mail from you, and I don't want your
birdseed, either!

----- =_aaaaaaaaaa0
Content-Type: message/delivery-status

Reporting-UA: sieve; GNU Mailutils 0.1.3
Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
Final-Recipient: RFC822; roadrunner@acme.example.com
Action: deleted
Disposition: automatic-action/MDN-sent-automatically;deleted
Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800

----- =_aaaaaaaaaa0
Content-Type: message/rfc822

From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you

I've got some great birdseed over here at my place.
Want to buy it?
----- =_aaaaaaaaaa0

If the reason argument is rather long, the common approach is to use the combination of the text: and #include keywords, e.g.:

if header :mime :matches "Content-Type"
          [ "*application/msword;*", "*audio/x-midi*" ]
  {
    reject text:
#include "nomsword.txt"
    .
    ;
  }

Action: redirect address

The redirect action is used to send the message to another user at a supplied address, as a mail forwarding feature does. This action makes no changes to the message body or existing headers, but it may add new headers. It also modifies the envelope recipient.

The redirect command performs an MTA-style “forward” — that is, what you get from a .forward file using sendmail under UNIX. The address on the SMTP envelope is replaced with the one on the redirect command and the message is sent back out. Notice, that it differs from the MUA-style forward, which creates a new message with a different sender and message ID, wrapping the old message in a new one.

5.7.2 External Actions

GNU Mailutils is shipped with a set of external Sieve actions. These actions are compiled as loadable modules and must be required prior to use (see Require Statement).

Action: moderator [:keep] [:address address(string)] [:source sieve-file(string)] [:program sieve-text(string)]

Synopsis:

require "moderator"
moderator args;

Description: This action is a moderator robot for Mailman-driven mail archives. A Mailman moderation request is a MIME message consisting of the following three parts:

N	Content-Type	Description
1	text/plain	Introduction for the human reader.
2	message/rfc822	Original submission.
3	message/rfc822	Mailman control message.

Replying to part 3 (keeping the subject intact) instructs Mailman to discard the original submission.

Replying to part 3 while adding an ‘Approved:’ header with the list password in it approves the submission.

The moderator action spawns an inferior Sieve machine and filters the original submission (part 2) through it. If the inferior machine marks the message as deleted, the action replies to the control message, thereby causing the submission to be discarded. The ‘From:’ address of the reply can be modified using :address tag. After discarding the message, moderator marks it as deleted, unless it is given :keep tag.

If the :source tag is given, its argument specifies a Sieve source file to be used on the message. Otherwise, if :program is given, its argument supplies a Sieve program to be used on this message. At most one of these tags may be specified. Supplying them both, or supplying several instances of the same tag, is an error. The behavior of the action in this case is undefined.

If neither :program nor :source is given, moderator will create a copy of the existing Sieve machine and use it on the message.

The action checks the message structure: it will bail out if the message does not have exactly 3 MIME parts, or if parts 2 and 3 are not of ‘message/rfc822’ type. It is the responsibility of the caller to make sure the message is actually a valid Mailman moderation request (see the example below).

Example:

if allof(header :is "Sender" "mailman-bounces@gnu.org",
         header :is "X-List-Administrivia" "yes")
  {
     moderator :source "~/.sieve/mailman.sv";
  }

Action: pipe [:envelope] [:header] [:body] command(string)

Synopsis:

require "pipe";

pipe command

Description: The pipe action executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags :envelope, :header, and :body control what parts of the message to pipe to the command.

Example: The example below uses the putmail utility (see putmail) to forward the message to user ‘gray’ on the machine ‘mail.gnu.org’.

require "pipe";

pipe "/usr/bin/putmail smtp://gray@mail.gnu.org"

Action: vacation [:days ndays(number)] [:subject subject(string)] [:aliases addrlist(string-list)] [:noreply noreply-address(string-list)] [:reply_regex expr(string)] [:reply_prefix prefix(string)] [:sender email(string)] [:database path(string)] [:return_address email(string)] [:header headers(string-list)] [:mime] [:always_reply] [:rfc2822] [:file] text(string)

Syntax:

require "vacation";
vacation args;

Description: The vacation action returns a message with text to the sender. It is intended to inform the sender that the recipient is not currently reading his mail.

If the :file tag is present, text is treated as the name of the file to read the body of the reply message from. When used together with tag :rfc2822, the file should be formatted as a valid RFC 2822 message, i.e. headers followed by empty line and body. Headers may not contain ‘To’, ‘From’, and ‘Subject’, as these will be generated automatically.

If the :subject tag is given, its argument sets the subject of the message. Otherwise, the subject is formed by prefixing original subject with ‘Re:’, or the prefix given with the :reply_prefix tag. Before prefixing, any original prefixes matching extended regular expression expr (:reply_regex tag) are stripped from the subject line. If :reply_regex is not specified, the default regexp is ‘^re: *’.

Another headers can be added using the :header tag. Its argument is a list of header strings, each one having the form ‘"name:value"’. Additional whitespace is allowed on both sides of the colon.

The :aliases tag instructs vacation to handle messages for any address in addrlist in the same manner as those received for the user’s principal email.

Before processing, vacation compares the sender address with its address exclusion list. Elements of this list are extended case-insensitive regular expressions. If the sender address matches any of these expressions, the message will not be replied. The default exclusion list is:

    .*-REQUEST@.*
    .*-RELAY@.*
    .*-OWNER@.*
    ^OWNER-.*
    ^postmaster@.*
    ^UUCP@.*
    ^MAILER@.*
    ^MAILER-DAEMON@.*

New entries can be added to this list using :noreply tag.

The :days tag sets the reply interval. A reply is sent to each sender once in ndays days. GNU Sieve keeps track of sender addresses and dates in file .vacation stored in the user’s home directory. The file name can be changed using the :database tag.

The tag :always_reply instructs vacation to respond to the message regardless of whether the user email is listed as a recipient for the message.

This document was generated on January 2, 2022 using makeinfo.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

GNU Mailutils

General-Purpose Mail Package

5.7 Actions

5.7.1 Built-in Actions

5.7.2 External Actions