idnits 2.17.1 draft-ietf-jmap-sieve-03.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 (December 17, 2020) is 1226 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 December 17, 2020 5 Expires: June 20, 2021 7 JMAP for Sieve Scripts 8 draft-ietf-jmap-sieve-03 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 June 20, 2021. 32 Copyright Notice 34 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . . . . 26 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 two elements: 685 1. A "String" *name* of the Sieve action (e.g., "keep"). 687 2. A "String[*]" object containing named *arguments* for that 688 action (e.g., "flags" or "mailbox"). 690 o *notCompleted*: "Id[SetError]|null" 692 A map of the blob id to a SetError object for each message that 693 was not successfully processed by the script, or "null" if none. 694 A "serverFail" SetError (see Section 3.6.2 of [RFC8620]) MUST be 695 used to indicate a Sieve interpreter run-time error. 697 The following additional errors may be returned instead of the 698 "SieveScript/test" response: 700 o "invalidScript": The script content is invalid (see Section 2.2). 702 o "notFound": The script referenced by the id could not be found. 704 o "rateLimit": The number of recent test method calls has reached a 705 server-defined limit. 707 o "requestTooLarge": The total number of emailBlobIds exceeds the 708 maximum number the server is willing to process in a single test 709 method call. 711 o "serverFail": The script failed preparation to be executed for 712 some other reason. 714 The name to use for each action argument in the response is a direct 715 mapping of the argument names as given in the specification of each 716 action. Tagged and optional arguments MUST use the name of the tag, 717 minus the leading ":". Positional arguments MUST use the name of the 718 argument inside of the angle brackets ("<" and ">") in the "Usage" 719 line in the specification for the action. 721 The JSON data type to use for each argument value is a direct mapping 722 from its Sieve data type, per the following table: 724 +-------------+----------------+ 725 | Sieve Type | JSON Type | 726 +-------------+----------------+ 727 | Number | Number | 728 | String | String | 729 | String List | String[] | 730 | no value | Boolean (true) | 731 +-------------+----------------+ 733 Recommendations for constructing the list of arguments are as 734 follows: 736 o Optional arguments in which the value is supplied by the Sieve 737 interpreter SHOULD be included (e.g., ":from" and ":subject" 738 arguments to the "vacation" [RFC5230] action). 740 o Optional arguments in which the value is implicitly supplied by a 741 Sieve variable SHOULD be included (e.g., "keep" or "fileinto" 742 actions without an explicit ":flags" argument, but "imap4flags" 743 [RFC5232] have been set on the internal variable). 745 o Optional arguments in which the value is the specfied default MAY 746 be omitted. 748 o Tagged arguments that are only used to determine whether the 749 action will be executed and have no impact on the result of the 750 action MAY be omitted (e.g., ":days" and ":addresses" arguments to 751 the vacation action). 753 2.5.1. Example 755 Assume that the following script has been created and has blob id 756 "S123". 758 require [ "imapflags", "editheader", "vacation", "fcc" ]; 759 setflag "$SieveFiltered"; 760 addheader :last "X-Sieve-Filtered" "yes"; 761 vacation :days 3 :fcc "INBOX.Sent" :flags "\\Answered" text: 762 Gone fishing. 763 . 764 ; 766 Assume that the following email has been uploaded and assigned blob 767 id "B456". 769 From: "Some Example Sender" 770 To: ken@example.com 771 Subject: test email 772 Date: Wed, 23 Sep 2020 12:11:11 -0500 773 Content-Type: text/plain; charset="UTF-8" 774 MIME-Version: 1.0 776 This is a test email. 778 The following request executes the script against the email and 779 provides envelope information for use by the "vacation" action. 781 { 782 "using": [ 783 "urn:ietf:params:jmap:core", 784 "urn:ietf:params:jmap:sieve", 785 "urn:ietf:params:jmap:mail" 786 ], 787 "methodCalls": [ 788 [ 789 "SieveScript/test", 790 { 791 "accountId": "ken", 792 "scriptBlobId": "S123", 793 "emailBlobIds": [ 794 "B456" 795 ], 796 "envelope": { 797 "mailFrom": { 798 "email": "example@example.net", 799 "parameters": null 800 }, 801 "rcptTo": [ 802 { 803 "email": "ken@example.com", 804 "parameters": null 805 } 806 ] 807 }, 808 "lastVacationResponse": null 809 }, 810 "R1" 811 ] 812 ] 813 } 814 The following response lists the actions that would be performed by 815 the script. 817 { 818 "methodResponses": [ 819 [ 820 "SieveScript/test", 821 { 822 "completed": { 823 "B456": [ 824 [ 825 "addheader", 826 { 827 "last": true, 828 "field-name": "X-Sieve-Filtered", 829 "value": "yes" 830 } 831 ], 832 [ 833 "vacation", 834 { 835 "fcc": "INBOX.Sent", 836 "flags": [ 837 "\\answered" 838 ], 839 "subject": "Auto: test email", 840 "from": "ken@example.com", 841 "reason": "Gone fishing." 842 } 843 ], 844 [ 845 "keep", 846 { 847 "flags": [ 848 "$SieveFiltered" 849 ] 850 } 851 ] 852 ] 853 }, 854 "notCompleted": null, 855 "accountId": "ken", 856 }, 857 "R1" 858 ] 859 ] 860 } 862 3. Compatibility with JMAP Vacation Response 864 Section 8 of [RFC8621] defines a VacationResponse object to represent 865 an autoresponder to incoming email messages. Servers that implement 866 the VacationResponse as a Sieve script that resides amongst other 867 user scripts are subject to the following requirements: 869 o MUST allow the VacationResponse Sieve script to be fetched by the 870 SieveScript/get (Section 2.1) method. 872 o MUST allow the VacationResponse Sieve script to be [de]activated 873 via the "onSuccessActivateScript" argument to the SieveScript/set 874 (Section 2.2) method. 876 o MUST NOT allow the VacationResponse Sieve script to be destroyed 877 or have its content updated by the SieveScript/set (Section 2.2) 878 method. Any such request MUST be rejected with a "forbidden" 879 SetError. A "description" property MAY be present with an 880 explanation that the script can only be modified by a 881 VacationResponse/set method. 883 4. Security Considerations 885 All security considerations of JMAP [RFC8620] and Sieve [RFC5228] 886 apply to this specification. 888 5. IANA Considerations 890 5.1. JMAP Capability Registration for "sieve" 892 IANA will register the "sieve" JMAP Capability as follows: 894 Capability Name: "urn:ietf:params:jmap:sieve" 896 Specification document: this document 898 Intended use: common 900 Change Controller: IETF 902 Security and privacy considerations: this document, Section 4 904 5.2. JMAP Error Codes Registry 906 The following sub-sections register two new error codes in the JMAP 907 Error Codes registry, as defined in [RFC8620]. 909 5.2.1. invalidScript 911 JMAP Error Code: invalidScript 913 Intended use: common 915 Change controller: IETF 917 Reference: This document, Section 2.2 919 Description: The SieveScript violates the Sieve grammar [RFC5228] 920 and/or one or more extensions mentioned in the script's "require" 921 statement(s) are not supported by the Sieve interpreter. 923 5.2.2. scriptIsActive 925 JMAP Error Code: scriptIsActive 927 Intended use: common 929 Change controller: IETF 931 Reference: This document, Section 2.2 933 Description: The client tried to destroy the active SieveScript. 935 6. Acknowledgments 937 The concepts in this document are based largely on those in 938 [RFC5804]. The author would like to thank the authors of that 939 document for providing both inspiration and some borrowed text for 940 this document. 942 The author would also like to thank the following individuals for 943 contributing their ideas and support for writing this specification: 944 Bron Gondwana, Neil Jenkins, Alexey Melnikov, and Ricardo Signes. 946 7. References 948 7.1. Normative References 950 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 951 Requirement Levels", BCP 14, RFC 2119, 952 DOI 10.17487/RFC2119, March 1997, 953 . 955 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 956 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 957 2003, . 959 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 960 Resource Identifier (URI): Generic Syntax", STD 66, 961 RFC 3986, DOI 10.17487/RFC3986, January 2005, 962 . 964 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 965 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 966 . 968 [RFC5228] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email 969 Filtering Language", RFC 5228, DOI 10.17487/RFC5228, 970 January 2008, . 972 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 973 DOI 10.17487/RFC5322, October 2008, 974 . 976 [RFC5435] Melnikov, A., Ed., Leiba, B., Ed., Segmuller, W., and T. 977 Martin, "Sieve Email Filtering: Extension for 978 Notifications", RFC 5435, DOI 10.17487/RFC5435, January 979 2009, . 981 [RFC6134] Melnikov, A. and B. Leiba, "Sieve Extension: Externally 982 Stored Lists", RFC 6134, DOI 10.17487/RFC6134, July 2011, 983 . 985 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 986 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 987 May 2017, . 989 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 990 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 991 2019, . 993 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application 994 Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, 995 August 2019, . 997 7.2. Informative References 999 [I-D.gondwana-jmap-blob] 1000 Gondwana, B., "JMAP Blob management extension", draft- 1001 gondwana-jmap-blob-01 (work in progress), November 2020. 1003 [RFC5230] Showalter, T. and N. Freed, Ed., "Sieve Email Filtering: 1004 Vacation Extension", RFC 5230, DOI 10.17487/RFC5230, 1005 January 2008, . 1007 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags 1008 Extension", RFC 5232, DOI 10.17487/RFC5232, January 2008, 1009 . 1011 [RFC5463] Freed, N., "Sieve Email Filtering: Ihave Extension", 1012 RFC 5463, DOI 10.17487/RFC5463, March 2009, 1013 . 1015 [RFC5804] Melnikov, A., Ed. and T. Martin, "A Protocol for Remotely 1016 Managing Sieve Scripts", RFC 5804, DOI 10.17487/RFC5804, 1017 July 2010, . 1019 Appendix A. Change History (To be removed by RFC Editor before 1020 publication) 1022 Changes since ietf-02: 1024 o Removed open issues. 1026 o Reverted back to using only blob ids for script content. 1028 o Added "rateLimit" and "requestTooLarge" to the list of possible 1029 error codes for /set method. 1031 o Added Compatibility with JMAP Vacation Response section. 1033 o Added RFC5228 to Security Considerations. 1035 o Miscellaneous editorial changes. 1037 Changes since ietf-01: 1039 o Removed normative references to ManageSieve (RFC 5804). 1041 o Added the 'maxSizeScriptName' capability. 1043 o Made the 'name' property in the SieveScript object optional. 1045 o Added requirements for the 'name' property in the SieveScript 1046 object. 1048 o Removed the 'blobId' property from the SieveScript object. 1050 o Removed the 'replaceOnCreate' argument from the /set method. 1052 o Removed the 'blobId' argument from the /validate method. 1054 o Removed the 'scriptBlobId' argument from, and added the 1055 'scriptContent' argument to, the /test method. 1057 o Editorial fixes from Neil Jenkins and Ricardo Signes. 1059 o Other miscellaneous text reorganization and editorial fixes. 1061 Changes since ietf-00: 1063 o Specified that changes made by onSuccessActivateScript MUST be 1064 reported in the /set response as created and/or updated as 1065 appropriate. 1067 o Reworked and specified more of the /test response based on 1068 implementation experience. 1070 Changes since murchison-01: 1072 o Explicitly stated that Sieve capability strings are case- 1073 sensitive. 1075 o errorDescription is now String|null. 1077 o Added /query method. 1079 o Added /test method. 1081 Changes since murchison-00: 1083 o Added IANA registration for "scriptIsActive" JMAP error code. 1085 o Added open issue about /set{create} with an existing script name. 1087 Author's Address 1089 Kenneth Murchison 1090 Fastmail US LLC 1091 1429 Walnut Street - Suite 1201 1092 Philadelphia, PA 19102 1093 USA 1095 Email: murch@fastmailteam.com