idnits 2.17.1 draft-ietf-jmap-sieve-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 3, 2021) is 1171 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-02) exists of draft-gondwana-jmap-blob-01 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP K. Murchison 3 Internet-Draft Fastmail 4 Intended status: Standards Track February 3, 2021 5 Expires: August 7, 2021 7 JMAP for Sieve Scripts 8 draft-ietf-jmap-sieve-04 10 Abstract 12 This document specifies a data model for managing Sieve scripts on a 13 server using the JSON Meta Application Protocol (JMAP). 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on August 7, 2021. 32 Copyright Notice 34 Copyright (c) 2021 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 51 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.3. Addition to the Capabilities Object . . . . . . . . . . . 3 53 1.3.1. urn:ietf:params:jmap:sieve . . . . . . . . . . . . . 3 54 2. Sieve Scripts . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. SieveScript/get . . . . . . . . . . . . . . . . . . . . . 6 56 2.2. SieveScript/set . . . . . . . . . . . . . . . . . . . . . 6 57 2.2.1. Examples . . . . . . . . . . . . . . . . . . . . . . 8 58 2.3. SieveScript/query . . . . . . . . . . . . . . . . . . . . 15 59 2.4. SieveScript/validate . . . . . . . . . . . . . . . . . . 15 60 2.5. SieveScript/test . . . . . . . . . . . . . . . . . . . . 16 61 2.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 19 62 3. Compatibility with JMAP Vacation Response . . . . . . . . . . 22 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 22 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 65 5.1. JMAP Capability Registration for "sieve" . . . . . . . . 22 66 5.2. JMAP Error Codes Registry . . . . . . . . . . . . . . . . 22 67 5.2.1. invalidScript . . . . . . . . . . . . . . . . . . . . 23 68 5.2.2. scriptIsActive . . . . . . . . . . . . . . . . . . . 23 69 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 70 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 71 7.1. Normative References . . . . . . . . . . . . . . . . . . 23 72 7.2. Informative References . . . . . . . . . . . . . . . . . 24 73 Appendix A. Change History (To be removed by RFC Editor before 74 publication) . . . . . . . . . . . . . . . . . . . . 25 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 77 1. Introduction 79 JMAP [RFC8620] (JSON Meta Application Protocol) is a generic protocol 80 for synchronizing data, such as mail, calendars or contacts, between 81 a client and a server. It is optimized for mobile and web 82 environments, and aims to provide a consistent interface to different 83 data types. 85 This specification defines a data model for managing Sieve [RFC5228] 86 scripts on a server using JMAP. The data model is designed to allow 87 a server to provide consistent access to the same scripts via 88 ManageSieve [RFC5804] as well as JMAP, however the functionality 89 offered over the two protocols may differ. 91 1.1. Notational Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in BCP 96 14 [RFC2119] [RFC8174] when, and only when, they appear in all 97 capitals, as shown here. 99 Type signatures, examples, and property descriptions in this document 100 follow the conventions established in Section 1.1 of [RFC8620]. Data 101 types defined in the core specification are also used in this 102 document. 104 Servers MUST support all properties specified for the new data type 105 defined in this document. 107 For compatibility with publishing requirements, line breaks have been 108 inserted inside long JSON strings, with the following continuation 109 lines indented. To form the valid JSON example, any line breaks 110 inside a string must be replaced with a space and any other white 111 space after the line break removed. 113 1.2. Terminology 115 The same terminology is used in this document as in the core JMAP 116 specification, see [RFC8620], Section 1.6. 118 The term SieveScript (with this specific capitalization) is used to 119 refer to the data type defined in this document and instances of 120 those data types. 122 1.3. Addition to the Capabilities Object 124 The capabilities object is returned as part of the JMAP Session 125 object; see [RFC8620], Section 2. This document defines one 126 additional capability URI. 128 1.3.1. urn:ietf:params:jmap:sieve 130 This represents support for the SieveScript data type and associated 131 API methods. The value of this property in the JMAP Session 132 capabilities property is an empty object. 134 The value of this property in an account's accountCapabilities 135 property is an object that MUST contain the following information on 136 server capabilities: 138 o *supportsTest*: "Boolean" 139 If true, the server supports the SieveScript/test (Section 2.5) 140 method. 142 o *maxSizeScriptName*: "UnsignedInt" 144 The maximum length, in (UTF-8) octets, allowed for the name of a 145 SieveScript. For compatibility with ManageSieve, this MUST be at 146 least 512 (up to 128 Unicode characters). 148 o *maxSizeScript*: "UnsignedInt|null" 150 The maximum size (in octets) of a Sieve script the server is 151 willing to store for the user, or "null" for no limit. 153 o *maxNumberScripts*: "UnsignedInt|null" 155 The maximum number of Sieve scripts the server is willing to store 156 for the user, or "null" for no limit. 158 o *maxNumberRedirects*: "UnsignedInt|null" 160 The maximum number of Sieve "redirect" actions a script can 161 perform during a single evaluation or "null" for no limit. Note 162 that this is different from the total number of "redirect" actions 163 a script can contain. 165 o *sieveExtensions*: "String[]" 167 A list of case-sensitive Sieve capability strings (as listed in 168 Sieve "require" action; see [RFC5228], Section 3.2) indicating the 169 extensions supported by the Sieve engine. 171 o *notificationMethods*: "String[]|null" 172 A list of URI schema parts [RFC3986] for notification methods 173 supported by the Sieve "enotify" [RFC5435] extension, or "null" if 174 the extension is not supported by the Sieve engine. 176 o *externalLists*: "String[]|null" 178 A list of URI schema parts [RFC3986] for externally stored list 179 types supported by the Sieve "extlists" [RFC6134] extension, or 180 "null" if the extension is not supported by the Sieve engine. 182 2. Sieve Scripts 184 A *SieveScript* object represents a single Sieve [RFC5228] script for 185 filtering email messages at time of final delivery. 187 A *SieveScript* object has the following properties: 189 o *id*: "Id" (immutable; server-set) 191 The id of the script. 193 o *name*: "String|null" (optional; default is server-dependent) 195 User-visible name for the SieveScript. If non-null, this MUST be 196 a Net-Unicode [RFC5198] string of at least 1 character in length, 197 subject to the maximum size given in the capability object. For 198 compatibility with ManageSieve, servers MUST reject names that 199 contain control characters. Servers MAY reject names that violate 200 server policy (e.g., names containing slash (/)). The name MUST 201 be unique among all SieveScripts within an account. 203 o *blobId*: "Id" 205 The id of the blob containing the raw octets of the script. 207 The script MUST be UTF-8 [RFC3629] content of at least 1 character 208 in length, subject to the syntax of Sieve [RFC5228]. The script 209 MUST NOT contain any "require" statement(s) mentioning Sieve 210 capabiltity strings not present in the capability (Section 1.3.1) 211 object. Note that if the Sieve "ihave" [RFC5463] capability 212 string is present in the capability object, the script MAY mention 213 unrecognized/unsupported extensions in the "ihave" test. 215 o *isActive*: "Boolean" (server-set; default: false) 217 A user may have multiple SieveScripts on the server, yet only one 218 script may be used for filtering of incoming messages. This is 219 the active script. Users may have zero or one active script. The 220 SieveScript/set (Section 2.2) method is used for changing the 221 active script or disabling Sieve processing. 223 2.1. SieveScript/get 225 This is a standard "/get" method as described in [RFC8620], 226 Section 5.1. The _ids_ argument may be "null" to fetch all at once. 228 This method provides similar functionality to the GETSCRIPT and 229 LISTSCRIPTS commands in [RFC5804]. 231 2.2. SieveScript/set 233 This is a standard "/set" method as described in [RFC8620], 234 Section 5.3 but with the following additional request argument, which 235 may be omitted: 237 o *onSuccessActivateScript*: "Id|null" (optional) 239 If "null", the currently active SieveScript (if any) will be 240 deactivated if and only if all of the creations, modifications, 241 and destructions (if any) succeed. Otherwise, the id of the 242 SieveScript to activate if and only if all of the creations, 243 modifications, and destructions (if any) succeed. (For references 244 to SieveScript creations, this is equivalent to a creation- 245 reference, so the id will be the creation id prefixed with a "#".) 246 If this argument is not present in the request, the currently 247 active SieveScript (if any) will remain as such. 249 The id of any activated SieveScript MUST be reported in either the 250 "created" or "updated" argument in the response as appropriate. 251 The id of any deactivated SieveScript MUST be reported in the 252 "updated" argument in the response. 254 This method provides similar functionality to the PUTSCRIPT, 255 DELETESCRIPT, RENAMESCRIPT, and SETACTIVE commands in [RFC5804]. 257 Script content must first be uploaded as a blob using either the 258 standard upload mechanism (see [RFC8620] Section 6.1) or the JMAP 259 Blob management extension (see [I-D.gondwana-jmap-blob] Section 3.1). 261 If the SieveScript can not be created or updated because it would 262 result in two SieveScripts with the same name, the server MUST reject 263 the request with an "alreadyExists" SetError. An "existingId" 264 property of type "Id" MUST be included on the SetError object with 265 the id of the existing SieveScript. 267 If the SieveScript can not be created or updated because its size 268 exceeds the "maxSizeScript" limit, the server MUST reject the request 269 with a "tooLarge" SetError. 271 If the Sieve Script can not be created because it would exceed the 272 "maxNumberScripts" limit, the server MUST reject the request with an 273 "overQuota" SetError. 275 The active SieveScript MUST NOT be destroyed unless it is first 276 deactivated in a separate SieveScript/set method call. 278 The following extra SetError types are defined: 280 For "create" and "update": 282 o *invalidScript*: 284 The SieveScript content violates the Sieve [RFC5228] grammar and/ 285 or one or more extensions mentioned in the script's "require" 286 statement(s) are not supported by the Sieve interpreter. The 287 _description_ property on the SetError object SHOULD contain a 288 specific error message giving at least the line number of the 289 first error. 291 For "destroy": 293 o *scriptIsActive*: 295 The SieveScript is active. 297 2.2.1. Examples 299 Request (and response) to upload a script requiring the Imap4Flags 300 [RFC5232] Extension (assuming that the JMAP Upload URL has been 301 advertised in the JMAP Session object as having a path of "/jmap/ 302 upload/{accountId}/"): 304 POST /jmap/upload/ken/ HTTP/1.1 305 Host: jmap.example.com 306 Authorization: Basic a2VuOnBhc3N3b3Jk 307 Content-Type: application/sieve 308 Content-Length: 98 310 require "imapflags"; 312 if address :is ["To", "Cc"] "jmap@ietf.org" { 313 setflag "\\Flagged"; 314 } 316 HTTP/1.1 201 Created 317 Date: Thu, 10 Dec 2020 17:14:31 GMT 318 Content-Type: application/json; charset=utf-8 319 Content-Length: 171 321 { 322 "accountId": "ken", 323 "blobId": "Gabcc83e44a6e19991c4568d0b94e1767c83dd123", 324 "type": "application/sieve" 325 "size": 98 326 } 327 Request (and response) to create and activate a script using the 328 uploaded blob: 330 { 331 "using": [ "urn:ietf:params:jmap:core", 332 "urn:ietf:params:jmap:sieve" ], 333 "methodCalls": [ 334 ["SieveScript/set", { 335 "accountId": "ken", 336 "create": { "A": { 337 "name": null, 338 "blobId": "Gabcc83e44a6e19991c4568d0b94e1767c83dd123" 339 }, 340 "onSuccessActivateScript": "#A" 341 }, "0"] 342 ] 343 } 345 { 346 "methodResponses": [ 347 [ 348 "SieveScript/set", 349 { 350 "oldState": "1603741717.50737918-4096", 351 "newState": "1603741751.227268529-4096", 352 "created": { 353 "A": { 354 "id": "dd1b164f-8cdc-448c-9f54-60210b5f14ae", 355 "name": "ken-20201210T171432-0", 356 "blobId": "Sdd1b164f-8cdc-448c-9f54-60210b5f14ae", 357 "isActive": true 358 } 359 }, 360 "updated": null, 361 "destroyed": null, 362 "notCreated": null, 363 "notUpdated": null, 364 "notDestroyed": null, 365 "accountId": "ken" 366 }, 367 "0" 368 ] 369 ] 370 } 372 Request (and response) to update script content using the JMAP Blob 373 management extension [I-D.gondwana-jmap-blob]: 375 { 376 "using": [ "urn:ietf:params:jmap:core", 377 "urn:ietf:params:jmap:sieve", 378 "urn:ietf:params:jmap:blob" ], 379 "methodCalls": [ 380 ["Blob/set", { 381 "accountId": "ken", 382 "create": { "B": { 383 "data:asText": "redirect \"ken@example.com\"\r\n;", 384 "type": "application/sieve" 385 } 386 }, "1"], 387 ["SieveScript/set", { 388 "accountId": "ken", 389 "update": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { 390 "blobId": "#B" 391 } 392 } 393 }, "2"] 394 ] 395 } 397 { 398 "methodResponses": [ 399 [ 400 "Blob/set", 401 { 402 "oldState": null, 403 "newState": "1603741700.309607123-0128", 404 "created": { 405 "B": { 406 "id": "G969c83e44a6e10871c4568d0b94e1767c83ddeae", 407 "blobId": "G969c83e44a6e10871c4568d0b94e1767c83ddeae", 408 "type": "application/sieve", 409 "size": 29 410 } 411 }, 412 "updated": null, 413 "destroyed": null, 414 "notCreated": null, 415 "notUpdated": null, 416 "notDestroyed": null, 417 "accountId": "ken" 418 }, 419 "1" 420 ], 421 [ 422 "SieveScript/set", 423 { 424 "oldState": "1603741751.227268529-4096", 425 "newState": "1603742603.309607868-4096", 426 "created": null, 427 "updated": { 428 "dd1b164f-8cdc-448c-9f54-60210b5f14ae": null 429 }, 430 "destroyed": null, 431 "notCreated": null, 432 "notUpdated": null, 433 "notDestroyed": null, 434 "accountId": "ken" 435 }, 436 "2" 437 ] 438 ] 439 } 440 Request (and response) to update script name and deactivate: 442 { 443 "using": [ "urn:ietf:params:jmap:core", 444 "urn:ietf:params:jmap:sieve" ], 445 "methodCalls": [ 446 ["SieveScript/set", { 447 "accountId": "ken", 448 "update": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { 449 "name": "myscript" 450 } 451 }, 452 "onSuccessActivateScript": null 453 }, "3"] 454 ] 455 } 457 { 458 "methodResponses": [ 459 [ 460 "SieveScript/set", 461 { 462 "oldState": "1603742603.309607868-4096", 463 "newState": "1603742967.852315428-4096", 464 "created": null, 465 "updated": { 466 "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { 467 "isActive": false 468 } 469 }, 470 "destroyed": null, 471 "notCreated": null, 472 "notUpdated": null, 473 "notDestroyed": null, 474 "accountId": "ken" 475 }, 476 "3" 477 ] 478 ] 479 } 480 Request (and response) to activate a script: 482 { 483 "using": [ "urn:ietf:params:jmap:core", 484 "urn:ietf:params:jmap:sieve" ], 485 "methodCalls": [ 486 ["SieveScript/set", { 487 "accountId": "ken", 488 "onSuccessActivateScript": "dd1b164f-8cdc-448c-9f54-60210b5f14ae" 489 }, "4"] 490 ] 491 } 493 { 494 "methodResponses": [ 495 [ 496 "SieveScript/set", 497 { 498 "oldState": "1603742967.852315428-4096", 499 "newState": "1603744460.316617118-4096", 500 "created": null, 501 "updated": { 502 "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { 503 "isActive": true 504 } 505 }, 506 "destroyed": null, 507 "notCreated": null, 508 "notUpdated": null, 509 "notDestroyed": null, 510 "accountId": "ken" 511 }, 512 "4" 513 ] 514 ] 515 } 517 Requests (and responses) to deactivate and destroy the active script: 519 { 520 "using": [ "urn:ietf:params:jmap:core", 521 "urn:ietf:params:jmap:sieve" ], 522 "methodCalls": [ 523 ["SieveScript/set", { 524 "accountId": "ken", 525 "onSuccessActivateScript": null 526 }, "5"], 527 ["SieveScript/set", { 528 "accountId": "ken", 529 "destroy": [ "dd1b164f-8cdc-448c-9f54-60210b5f14ae" ] 530 }, "6"] 531 ] 532 } 534 { 535 "methodResponses": [ 536 [ 537 "SieveScript/set", 538 { 539 "oldState": "1603744460.316617118-4096", 540 "newState": "1603744637.575375572-4096", 541 "created": null, 542 "updated": null, 543 "updated": { 544 "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { 545 "isActive": false 546 } 547 }, 548 "destroyed": null, 549 "notCreated": null, 550 "notUpdated": null, 551 "notDestroyed": null, 552 "accountId": "ken" 553 }, 554 "5" 555 ], 556 [ 557 "SieveScript/set", 558 { 559 "oldState": "1603744637.575375572-4096", 560 "newState": "1603744637.854390875-4096", 561 "created": null, 562 "updated": null, 563 "destroyed": [ 564 "dd1b164f-8cdc-448c-9f54-60210b5f14ae" 565 ], 566 "notCreated": null, 567 "notUpdated": null, 568 "notDestroyed": null, 569 "accountId": "ken" 570 }, 571 "6" 572 ] 573 ] 574 } 576 2.3. SieveScript/query 578 This is a standard "/query" method as described in [RFC8620], 579 Section 5.5. A _FilterCondition_ object has the following 580 properties, either of which may be omitted: 582 o *name*: "String" 584 The SieveScript "name" property contains the given string. 586 o *isActive*: "Boolean" 588 The "isActive" property of the SieveScript must be identical to 589 the value given to match the condition. 591 The following SieveScript properties MUST be supported for sorting: 593 o *name* 595 o *isActive* 597 2.4. SieveScript/validate 599 This method is used by the client to verify Sieve script validity 600 without storing the script on the server, providing similar 601 functionality to the CHECKSCRIPT command in [RFC5804]. 603 The method takes the following arguments: 605 o *accountId*: "Id" 607 The id of the account to use. 609 o *blobId*: "Id" 611 The id of the blob containing the raw octets of the script to 612 validate, subject to the same requirements in Section 2. 614 The response has the following arguments: 616 o *accountId*: "Id" 618 The id of the account used for this call. 620 o *error*: "SetError|null" 622 A "invalidScript" SetError object if the script content is invalid 623 (see Section 2.2), or "null" if the script content is valid. 625 As with the SieveScript/set (Section 2.2) method, script content must 626 first be uploaded as a blob using either the standard upload 627 mechanism (see [RFC8620] Section 6.1) or the JMAP Blob management 628 extension (see [I-D.gondwana-jmap-blob] Section 3.1). 630 2.5. SieveScript/test 632 This method is used by the client to ask the Sieve interpreter to 633 evaluate a Sieve script against a set of emails and report the 634 actions that would be performed for each. 636 When calling this method the "using" property of the Request object 637 MUST contain the capabilities "urn:ietf:params:jmap:sieve" and 638 "urn:ietf:params:jmap:mail". The latter is required due to the use 639 of blob ids which may reference Email objects and the use of the 640 Envelope object, as described below. 642 The *SieveScript/test* method takes the following arguments: 644 o *accountId*: "Id" 646 The id of the account to use. 648 o *scriptBlobId*: "String" 650 The id of the blob containing the raw octets of the script to 651 validate, subject to the same requirements in Section 2. 653 o *emailBlobIds*: "Id[]" 654 The ids representing the raw octets of the [RFC5322] messages to 655 test against. 657 o *envelope*: "Envelope|null" 659 Information that the Sieve interpreter should assume was present 660 in the SMTP transaction that delivered the message when evaluating 661 "envelope" tests. If "null", all "envelope" tests MUST evaluate 662 to false. See Section 7 of [RFC8621] for the contents of the 663 Envelope object. 665 o *lastVacationResponse*: "UTCDate|null" 667 The UTC date-time at which the Sieve interpreter should assume 668 that it last auto-replied to the sender of the message, or "null" 669 if the Sieve interpreter should assume that it has not auto- 670 replied to the sender. 672 The response has the following arguments: 674 o *accountId*: "Id" 676 The id of the account used for this call. 678 o *completed*: "Id[Action[]]|null" 680 A map of the blob id to a set of _Action_ types for each message 681 successfully processed by the script, or "null" if none. The 682 _Action_ data type is a tuple, represented as a JSON array 683 containing three elements: 685 1. A "String" *name* of the Sieve action (e.g., "keep"). 687 2. A "String[*]" object containing any named (tagged) arguments 688 for the action. The name MUST be the tag for the argument as 689 given in the specification of the action (e.g., ":flags"). 691 This may be an empty object if the action does not have any 692 tagged arguments, or none were specified in the Sieve script 693 (e.g., discard [RFC5228] or ereject [RFC5429] action). 695 3. An "*[]" array containing any positional arguments for the 696 action in the order as given in the specification of the 697 action. This may be an empty array if the action does not 698 have any positional arguments (e.g., discard [RFC5228] or keep 699 [RFC5228] action). 701 o *notCompleted*: "Id[SetError]|null" 703 A map of the blob id to a SetError object for each message that 704 was not successfully processed by the script, or "null" if none. 705 A "serverFail" SetError (see Section 3.6.2 of [RFC8620]) MUST be 706 used to indicate a Sieve interpreter run-time error. 708 The following additional errors may be returned instead of the 709 "SieveScript/test" response: 711 o "invalidScript": The script content is invalid (see Section 2.2). 713 o "notFound": The script referenced by the id could not be found. 715 o "rateLimit": The number of recent test method calls has reached a 716 server-defined limit. 718 o "requestTooLarge": The total number of emailBlobIds exceeds the 719 maximum number the server is willing to process in a single test 720 method call. 722 o "serverFail": The script failed preparation to be executed for 723 some other reason. 725 The JSON data type to use for each argument value is a direct mapping 726 from its Sieve data type, per the following table: 728 +-------------------+----------------+ 729 | Sieve Type | JSON Type | 730 +-------------------+----------------+ 731 | Number | Number | 732 | String | String | 733 | String List | String[] | 734 | tag with no value | Boolean (true) | 735 +-------------------+----------------+ 737 Recommendations for constructing the list of arguments are as 738 follows: 740 o Optional arguments in which the value is supplied by the Sieve 741 interpreter SHOULD be included (e.g., ":from" and ":subject" 742 arguments to the "vacation" [RFC5230] action). 744 o Optional arguments in which the value is implicitly supplied by a 745 Sieve variable SHOULD be included (e.g., "keep" or "fileinto" 746 actions without an explicit ":flags" argument, but "imap4flags" 747 [RFC5232] have been set on the internal variable). 749 o Optional arguments in which the value is the specfied default MAY 750 be omitted. 752 o Tagged arguments that are only used to determine whether the 753 action will be executed and have no impact on the result of the 754 action MAY be omitted (e.g., ":days" and ":addresses" arguments to 755 the vacation action). 757 2.5.1. Example 759 Assume that the following script has been created and has blob id 760 "S123". 762 require [ "imapflags", "editheader", "vacation", "fcc" ]; 763 setflag "$SieveFiltered"; 764 addheader :last "X-Sieve-Filtered" "yes"; 765 vacation :days 3 :fcc "INBOX.Sent" :flags "\\Answered" text: 766 Gone fishing. 767 . 768 ; 769 Assume that the following email has been uploaded and assigned blob 770 id "B456". 772 From: "Some Example Sender" 773 To: ken@example.com 774 Subject: test email 775 Date: Wed, 23 Sep 2020 12:11:11 -0500 776 Content-Type: text/plain; charset="UTF-8" 777 MIME-Version: 1.0 779 This is a test email. 781 The following request executes the script against the email and 782 provides envelope information for use by the "vacation" action. 784 { 785 "using": [ 786 "urn:ietf:params:jmap:core", 787 "urn:ietf:params:jmap:sieve", 788 "urn:ietf:params:jmap:mail" 789 ], 790 "methodCalls": [ 791 [ 792 "SieveScript/test", 793 { 794 "accountId": "ken", 795 "scriptBlobId": "S123", 796 "emailBlobIds": [ 797 "B456" 798 ], 799 "envelope": { 800 "mailFrom": { 801 "email": "example@example.net", 802 "parameters": null 803 }, 804 "rcptTo": [ 805 { 806 "email": "ken@example.com", 807 "parameters": null 808 } 809 ] 810 }, 811 "lastVacationResponse": null 812 }, 813 "R1" 814 ] 815 ] 816 } 817 The following response lists the actions that would be performed by 818 the script. 820 { 821 "methodResponses": [ 822 [ 823 "SieveScript/test", 824 { 825 "completed": { 826 "B456": [ 827 [ 828 "addheader", 829 { 830 ":last": true 831 }, 832 [ "X-Sieve-Filtered", "yes" ] 833 ], 834 [ 835 "vacation", 836 { 837 ":fcc": "INBOX.Sent", 838 ":flags": [ 839 "\\answered" 840 ], 841 ":subject": "Auto: test email", 842 ":from": "ken@example.com" 843 }, 844 [ "Gone fishing." ] 845 ], 846 [ 847 "keep", 848 { 849 ":flags": [ 850 "$SieveFiltered" 851 ] 852 }, 853 [ ] 854 ] 855 ] 856 }, 857 "notCompleted": null, 858 "accountId": "ken", 859 }, 860 "R1" 861 ] 862 ] 863 } 865 3. Compatibility with JMAP Vacation Response 867 Section 8 of [RFC8621] defines a VacationResponse object to represent 868 an autoresponder to incoming email messages. Servers that implement 869 the VacationResponse as a Sieve script that resides amongst other 870 user scripts are subject to the following requirements: 872 o MUST allow the VacationResponse Sieve script to be fetched by the 873 SieveScript/get (Section 2.1) method. 875 o MUST allow the VacationResponse Sieve script to be [de]activated 876 via the "onSuccessActivateScript" argument to the SieveScript/set 877 (Section 2.2) method. 879 o MUST NOT allow the VacationResponse Sieve script to be destroyed 880 or have its content updated by the SieveScript/set (Section 2.2) 881 method. Any such request MUST be rejected with a "forbidden" 882 SetError. A "description" property MAY be present with an 883 explanation that the script can only be modified by a 884 VacationResponse/set method. 886 4. Security Considerations 888 All security considerations of JMAP [RFC8620] and Sieve [RFC5228] 889 apply to this specification. 891 5. IANA Considerations 893 5.1. JMAP Capability Registration for "sieve" 895 IANA will register the "sieve" JMAP Capability as follows: 897 Capability Name: "urn:ietf:params:jmap:sieve" 899 Specification document: this document 901 Intended use: common 903 Change Controller: IETF 905 Security and privacy considerations: this document, Section 4 907 5.2. JMAP Error Codes Registry 909 The following sub-sections register two new error codes in the JMAP 910 Error Codes registry, as defined in [RFC8620]. 912 5.2.1. invalidScript 914 JMAP Error Code: invalidScript 916 Intended use: common 918 Change controller: IETF 920 Reference: This document, Section 2.2 922 Description: The SieveScript violates the Sieve grammar [RFC5228] 923 and/or one or more extensions mentioned in the script's "require" 924 statement(s) are not supported by the Sieve interpreter. 926 5.2.2. scriptIsActive 928 JMAP Error Code: scriptIsActive 930 Intended use: common 932 Change controller: IETF 934 Reference: This document, Section 2.2 936 Description: The client tried to destroy the active SieveScript. 938 6. Acknowledgments 940 The concepts in this document are based largely on those in 941 [RFC5804]. The author would like to thank the authors of that 942 document for providing both inspiration and some borrowed text for 943 this document. 945 The author would also like to thank the following individuals for 946 contributing their ideas and support for writing this specification: 947 Bron Gondwana, Neil Jenkins, Alexey Melnikov, and Ricardo Signes. 949 7. References 951 7.1. Normative References 953 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 954 Requirement Levels", BCP 14, RFC 2119, 955 DOI 10.17487/RFC2119, March 1997, 956 . 958 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 959 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 960 2003, . 962 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 963 Resource Identifier (URI): Generic Syntax", STD 66, 964 RFC 3986, DOI 10.17487/RFC3986, January 2005, 965 . 967 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 968 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 969 . 971 [RFC5228] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email 972 Filtering Language", RFC 5228, DOI 10.17487/RFC5228, 973 January 2008, . 975 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 976 DOI 10.17487/RFC5322, October 2008, 977 . 979 [RFC5435] Melnikov, A., Ed., Leiba, B., Ed., Segmuller, W., and T. 980 Martin, "Sieve Email Filtering: Extension for 981 Notifications", RFC 5435, DOI 10.17487/RFC5435, January 982 2009, . 984 [RFC6134] Melnikov, A. and B. Leiba, "Sieve Extension: Externally 985 Stored Lists", RFC 6134, DOI 10.17487/RFC6134, July 2011, 986 . 988 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 989 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 990 May 2017, . 992 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 993 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 994 2019, . 996 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application 997 Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, 998 August 2019, . 1000 7.2. Informative References 1002 [I-D.gondwana-jmap-blob] 1003 Gondwana, B., "JMAP Blob management extension", draft- 1004 gondwana-jmap-blob-01 (work in progress), November 2020. 1006 [RFC5230] Showalter, T. and N. Freed, Ed., "Sieve Email Filtering: 1007 Vacation Extension", RFC 5230, DOI 10.17487/RFC5230, 1008 January 2008, . 1010 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 1011 Extension", RFC 5232, DOI 10.17487/RFC5232, January 2008, 1012 . 1014 [RFC5429] Stone, A., Ed., "Sieve Email Filtering: Reject and 1015 Extended Reject Extensions", RFC 5429, 1016 DOI 10.17487/RFC5429, March 2009, 1017 . 1019 [RFC5463] Freed, N., "Sieve Email Filtering: Ihave Extension", 1020 RFC 5463, DOI 10.17487/RFC5463, March 2009, 1021 . 1023 [RFC5804] Melnikov, A., Ed. and T. Martin, "A Protocol for Remotely 1024 Managing Sieve Scripts", RFC 5804, DOI 10.17487/RFC5804, 1025 July 2010, . 1027 Appendix A. Change History (To be removed by RFC Editor before 1028 publication) 1030 Changes since ietf-03: 1032 o SieveScript/test: Moved positional arguments into their own array 1033 (because the specfications don't use a consistent method for 1034 defining the action syntax or naming of positional arguments). 1036 Changes since ietf-02: 1038 o Removed open issues. 1040 o Reverted back to using only blob ids for script content. 1042 o Added "rateLimit" and "requestTooLarge" to the list of possible 1043 error codes for /set method. 1045 o Added Compatibility with JMAP Vacation Response section. 1047 o Added RFC5228 to Security Considerations. 1049 o Miscellaneous editorial changes. 1051 Changes since ietf-01: 1053 o Removed normative references to ManageSieve (RFC 5804). 1055 o Added the 'maxSizeScriptName' capability. 1057 o Made the 'name' property in the SieveScript object optional. 1059 o Added requirements for the 'name' property in the SieveScript 1060 object. 1062 o Removed the 'blobId' property from the SieveScript object. 1064 o Removed the 'replaceOnCreate' argument from the /set method. 1066 o Removed the 'blobId' argument from the /validate method. 1068 o Removed the 'scriptBlobId' argument from, and added the 1069 'scriptContent' argument to, the /test method. 1071 o Editorial fixes from Neil Jenkins and Ricardo Signes. 1073 o Other miscellaneous text reorganization and editorial fixes. 1075 Changes since ietf-00: 1077 o Specified that changes made by onSuccessActivateScript MUST be 1078 reported in the /set response as created and/or updated as 1079 appropriate. 1081 o Reworked and specified more of the /test response based on 1082 implementation experience. 1084 Changes since murchison-01: 1086 o Explicitly stated that Sieve capability strings are case- 1087 sensitive. 1089 o errorDescription is now String|null. 1091 o Added /query method. 1093 o Added /test method. 1095 Changes since murchison-00: 1097 o Added IANA registration for "scriptIsActive" JMAP error code. 1099 o Added open issue about /set{create} with an existing script name. 1101 Author's Address 1103 Kenneth Murchison 1104 Fastmail US LLC 1105 1429 Walnut Street - Suite 1201 1106 Philadelphia, PA 19102 1107 USA 1109 Email: murch@fastmailteam.com