Sieve Email Filtering: Editheader Extension
RFC 5293

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 11

Network Working Group                                         J. Degener
Request for Comments: 5293                                   P. Guenther
Category: Standards Track                                 Sendmail, Inc.
                                                             August 2008

              Sieve Email Filtering: Editheader Extension

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This document defines two new actions for the "Sieve" email filtering
   language that add and delete email header fields.

1.  Introduction

   Email header fields are a flexible and easy-to-understand means of
   communication between email processors.  This extension enables sieve
   scripts to interact with other components that consume or produce
   header fields by allowing the script to delete and add header fields.

2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [KEYWORDS].

   Conventions for notations are as in Section 1.1 of [SIEVE], including
   use of the "Usage:" label for the definition of action and tagged
   arguments syntax.

   The term "header field" is used here as in [IMAIL] to mean a logical
   line of an email message header.

3.  Capability Identifier

   The capability string associated with the extension defined in this
   document is "editheader".

Degener & Guenther          Standards Track                     [Page 1]
RFC 5293      Sieve Email Filtering: Editheader Extension    August 2008

4.  Action addheader

   Usage: "addheader" [":last"] <field-name: string> <value: string>

   The addheader action adds a header field to the existing message
   header.  If the field-name is not a valid 7-bit US-ASCII header field
   name, as described by the [IMAIL] "field-name" nonterminal syntax
   element, the implementation MUST flag an error.  The addheader action
   does not affect Sieve's implicit keep.

   If the specified field value does not match the [IMAIL]
   "unstructured" nonterminal syntax element or exceeds a length limit
   set by the implementation, the implementation MUST either flag an
   error or encode the field using folding white space and the encodings
   described in [MIME3] or [MIMEPARAM] to be compliant with [IMAIL].

   An implementation MAY impose a length limit onto the size of the
   encoded header field; such a limit MUST NOT be less than 998
   characters, not including the terminating CRLF supplied by the
   implementation.

   By default, the header field is inserted at the beginning of the
   existing message header.  If the optional flag ":last" is specified,
   it is appended at the end.

   Example:

        /* Don't redirect if we already redirected */
        if not header :contains "X-Sieve-Filtered"
                ["<kim@job.example.com>", "<kim@home.example.com>"]
        {
                addheader "X-Sieve-Filtered" "<kim@job.example.com>";
                redirect "kim@home.example.com";
        }

5.  Action deleteheader

      Usage: "deleteheader" [":index" <fieldno: number> [":last"]]
                   [COMPARATOR] [MATCH-TYPE]
                   <field-name: string>
                   [<value-patterns: string-list>]

   By default, the deleteheader action deletes all occurrences of the
   named header field.  The deleteheader action does not affect Sieve's
   implicit keep.

Degener & Guenther          Standards Track                     [Page 2]
RFC 5293      Sieve Email Filtering: Editheader Extension    August 2008

   The field-name is mandatory and always matched as a case-insensitive
   US-ASCII string.  If the field-name is not a valid 7-bit header field
   name as described by the [IMAIL] "field-name" nonterminal syntax
   element, the implementation MUST flag an error.

   The value-patterns, if specified, restrict which occurrences of the
   header field are deleted to those whose values match any of the
   specified value-patterns, the matching being according to the match-
   type and comparator and performed as if by the "header" test.  In
   particular, leading and trailing whitespace in the field values is
   ignored.  If no value-patterns are specified, then the comparator and
   match-type options are silently ignored.

   If :index <fieldno> is specified, the attempts to match a value are
   limited to the <fieldno> occurrence of the named header field,
   beginning at 1, the first named header field.  If :last is specified,
   the count is backwards; 1 denotes the last named header field, 2 the