RFC 6558
Sieve Extension for Converting Messages before Delivery
RFC 6558: Sieve Extension for Converting Messages before Delivery 💌
This one's a Standards Track document from March 2012 (ISSN 2070-1721). It was written by A. Melnikov of Isode Limited, B. Leiba, and K. Li of Huawei Technologies. The title block doesn't list anything it obsoletes or updates.
Abstract 💖
This doc explains how the "CONVERT" IMAP extension can be used inside the Sieve mail filtering language to transform messages before they get their final delivery. 📬
Status of This Memo 📋
This is an Internet Standards Track document. ✨
It's a product of the Internet Engineering Task Force (IETF), so it reflects the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741.
For the current status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc6558. 🔗
Copyright Notice ©️
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at http://trustee.ietf.org/license-info, as in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License. ⚖️
Table of Contents 🗂️
1. Introduction ....................................................2
1.1. Conventions Used in This Document ..........................2
2. "convert" Action ................................................2
2.1. Interaction with Other Tests and Actions ...................3
2.2. "convert" as a Test ........................................4
3. Examples ........................................................5
3.1. Example 1 ..................................................5
3.2. Example 2 ..................................................5
3.3. Example 3 ..................................................5
3.4. Example 4 ..................................................6
4. Security Considerations .........................................7
5. IANA Considerations .............................................7
6. Acknowledgements ................................................7
7. Normative References ............................................71. Introduction 🧚
Okay so the IMAP "CONVERT" extension [RFC5259] adds an IMAP command that lets the client control conversions on whole messages or on their body parts. 💅 This document defines a similar extension for the Sieve mail filtering language [RFC5228], and it reuses the conversion parameters and framework that IMAP CONVERT already set up. It's giving consistency. 🫶
1.1. 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 RFC 2119 [RFC2119]. 🔑
Notation conventions follow Sieve [RFC5228], Section 1.1. ✍️
2. "convert" Action 🔥
The usage looks like this:
Usage: convert <quoted-from-media-type: string>
<quoted-to-media-type: string>
<transcoding-params: string-list>The "convert" action says that every body part whose media type [RFC2046] (sometimes called a "MIME type") is equal to <quoted-from-media-type> gets converted to the media type in <quoted-to-media-type>. The conversion uses the parameters listed in <transcoding-params>. Each conversion parameter value looks like this: "<transcoding-param-name>=<transcoding-param-value>". The <transcoding-param-name> and <transcoding-param-value> are defined in CONVERT [RFC5259]. Messages without any body parts of the <quoted-from-media-type> media type aren't touched at all. 🌸
You can pair "convert" with Sieve MIME Part Tests [RFC5703] when only some of the body parts need converting, or when different body parts need different conversions. When "convert" shows up inside a "foreverypart" loop, it only applies to the body part being processed and doesn't touch any other body parts (see Section 3.2 for an example). 🧩
When "convert" sits outside a "foreverypart" loop, the conversion applies equally to all body parts. In other words, every body part that has the "quoted-from-media-type" gets converted, using the same transcoding parameters. 🌈
A single "convert" action only ever applies once to any given body part. For example, if << convert "image/jpeg" "image/jpeg" ["pix-x=100","pix-y=120"] >> turns a bigger JPEG into a 100 x 120 one, that's the end of that "convert" action for that body part. The action won't treat the new JPEG body part produced by the conversion as something new to process. 🖼️
If a "convert" action can't be completed, maybe because the conversion failed or because the requested conversion isn't available, then that action MUST terminate and leave the message unchanged, rolling back any other conversions that action had done. Script processing keeps going, and prior or subsequent "convert" actions aren't affected. No error condition is raised, and no partial conversions from a single "convert" action are allowed. 🙅♀️
Implementations might delay the actual conversion until its results are needed for script processing, so they don't waste work on conversions that don't matter. Picture this: a "convert" action gets processed, but then a "discard" action happens, so the conversion never needed to actually run. 🗑️
Real conversions can put a serious load on the server. Expensive conversions on lots of body parts can become an attack vector, and even legit ones can create an unacceptable load. Servers MAY refuse conversions, or run them at lower priority, which slows down the requesting process so it doesn't hurt service for other processes. 🛡️
2.1. Interaction with Other Tests and Actions 🤝
Whether or not the conversion has actually been done yet, a successful "convert" action effectively changes the message. All later actions, including other "convert" actions, apply to the changed message. The "convert" action doesn't affect whether other actions apply: anything that could run before the "convert" can still run afterward on the changed message. 💫
When a disposition-type action, like "fileinto" or "redirect", shows up, the state of the message with respect to conversions gets "locked in" for that action. Whether the implementation does the action right then or batches it for later, it MUST perform the action on the message as it stood at that moment, and it MUST NOT include conversions that come later in the script. So the sequence "convert, fileinto, convert, fileinto" stores two different versions of the message. The first "fileinto" uses only the first conversion, while the second uses both. Section 3.4 shows how this can be used. 🗂️
Tests on the message and its parts also check the message after prior conversions have been done. The fourth block of Section 3.4 has an example of this. 🔍
Convert actions are cumulative, and each conversion works on the message as it stands after all earlier conversions. The fourth block of Section 3.4 shows how this can get tricky. 🌀
Since the implicit keep (see Section 2.10.2 of [RFC5228]) acts on the final state of the message, if it's in effect, all conversions are done before any implicit keep. 🏁
2.2. "convert" as a Test 🧪
To make it easy to check whether conversions are supported and successful, the "convert" action can also be used as a test. As a test, it tries to perform the requested conversion(s) and evaluates to "false" if and only if at least one conversion failed. A failure can happen because a conversion wasn't supported, or because the data couldn't be converted (maybe it got corrupted in transit or was mislabeled at the origin). 🕵️♀️
This creates a new type of Sieve action called a "testable action". Using it as a test is exactly the same as using it as an action, so it works as both an action and a test of that action's result at the same time. See Section 3.2 for an example. ✨
Defining this testable action doesn't change the definitions of any other actions. It doesn't mean other actions can be used as tests. Future extensions might define other testable actions, but those specs would have to clearly say so. 📝
3. Examples 🎀
3.1. Example 1 🍓
In this example, every "image/tiff" body part of the message gets converted to "image/jpeg" at 320x240 pixels. The converted message then goes through the implicit keep. 🥰
require ["convert"];
convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"];3.2. Example 2 📂
This one converts every "image/tiff" body part to "image/jpeg", same as Example 1. If the conversions work out, the messages get filed into a mailbox called "INBOX.pics". Other messages (the ones with no image/tiff body parts) go through the implicit keep and don't get converted. 💖
require ["mime", "fileinto", "convert"];
if header :mime :anychild :contenttype
"Content-Type" "image/tiff"
{
if (convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"])
{
fileinto "INBOX.pics";
}
}3.3. Example 3 🦋
Here only "image/tiff" body parts with a Content-Disposition of "inline" get converted. Matching parts bigger than 500 kilobytes become 640x480 pixels, and smaller ones become 320x240 pixels. The message disposition doesn't change, so the implicit keep stays in effect unless something else in the script changes that. 💜
require ["mime", "foreverypart", "fileinto", "convert"];
foreverypart
{
if header :mime :param "filename" :contains
"Content-Disposition" "inline"
{
if size :over "500K"
{
convert "image/tiff" "image/jpeg" ["pix-x=640","pix-y=480"];
} else {
convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"];
}
}
}
[... script continues ...]3.4. Example 4 💖
okay so this example is lowkey the most chaotic one 😭 it shows what happens when a bunch of "convert" actions and other disposition-type actions (like fileinto and redirect) start interacting in the same script. Read the comments, they explain the drama.
require ["mime", "foreverypart",
"fileinto", "redirect", "convert"];
# The first "if" block will convert all image/tiff body parts
# to 640x480 jpegs and will file the message
# into the "INBOX.pics" mailbox as converted at this point.
if header :mime :anychild :contenttype
"Content-Type" "image/tiff"
{
convert "image/tiff" "image/jpeg" ["pix-x=640","pix-y=480"];
fileinto "INBOX.pics";
}
# The second block, the "foreverypart" loop, will convert all
# inline jpegs to 320x240 resolution... including any tiff body
# parts that had been converted in the first block, above.
# Therefore, any tiff that had been converted to a 640x480 jpeg
# will be re-converted to a 320x240 jpeg here if its
# Content-Disposition is specified as "inline".
foreverypart
{
if header :mime :param "filename" :contains
"Content-Disposition" "inline"
{
convert "image/jpeg" "image/jpeg" ["pix-x=320","pix-y=240"];
}
}
# The third block will take any message that contains a header
# field called "Mobile-Link" and redirect it to the user's
# mobile address. The redirected message will include both
# conversions above, from block one and block two.
if exists "Mobile-Link"
{
redirect "joe@mobile.example.com";
}
# The fourth block will file the message into "Tiff" if it
# contains any tiff body parts. But because of the earlier
# conversion (in the first block), there will never be any
# tiff body parts, so this "fileinto" will never happen.
if header :mime :anychild :contenttype
"Content-Type" "image/tiff"
{
fileinto "Tiff";
}
# Now, at the end of the script processing, the Sieve
# processor will perform an implicit keep if none of
# the "fileinto" and "redirect" actions were taken.
# The kept message will include any conversions that
# were done (that is, any from the second block).4. Security Considerations 🔒
Okay, this part is serious bestie, so no cap, pay attention 👀. The security considerations from IMAP CONVERT [RFC5259] and Sieve [RFC5228] both apply to this document. Combining the two doesn't add any new security considerations of its own. 💅
5. IANA Considerations 🦋
IANA has added a registration to the "Sieve Extensions" registry, which is defined in RFC 5228. Here's what it looks like:
Capability name: convert
Description: adds a new Sieve test and action that enable Sieve
scripts to perform data conversions on the message being
delivered.
RFC number: RFC 6558
Contact address: The Sieve discussion list <sieve@ietf.org>6. Acknowledgements 🫶
The authors want to give a huge shoutout to everyone who shared key insights and reviewed and discussed the concepts of CONVERT in depth. You all are iconic 💖
Qian Sun contributed text to this document. Slay, Qian 👑
7. Normative References 📚
These are the references that this document depends on. Every entry is listed with its full details:
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
Language", RFC 5228, January 2008.
[RFC5259] Melnikov, A. and P. Coates, "Internet Message Access
Protocol - CONVERT Extension", RFC 5259, July 2008.
[RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part
Tests, Iteration, Extraction, Replacement, and Enclosure",
RFC 5703, October 2009.Authors' Addresses 💌
Here are the people who wrote it, with their contact details. Go say hi 🧚
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
URI: http://www.melnikov.ca/
Barry Leiba
Huawei Technologies
Phone: +1 646 827 0648
EMail: barryleiba@computer.org
URI: http://internetmessagingtechnology.org/
Kepeng Li
Huawei Technologies
Huawei Base, Bantian, Longgang District
Shenzhen, Guangdong 518129
P. R. China
Phone: +86-755-28974289
EMail: likepeng@huawei.com📦 where this page comes from
- ietf: rfc6558 2012-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms