This is notmuch-properties.info, produced by makeinfo version 4.8 from
notmuch-properties.texi.

Generated by Sphinx 1.4.8.
INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* notmuch-properties: (notmuch-properties.info). notmuch message property conventions and documentation
END-INFO-DIR-ENTRY

     notmuch 0.30, Oct 01, 2020

     Carl Worth and many others

     Copyright (C) 2009-2020, Carl Worth and many others


File: notmuch-properties.info,  Node: Top,  Next: SYNOPSIS,  Up: (dir)

notmuch-properties documentation
********************************

     notmuch 0.30, Oct 01, 2020

     Carl Worth and many others

     Copyright (C) 2009-2020, Carl Worth and many others

* Menu:

* SYNOPSIS::
* DESCRIPTION::
* CONVENTIONS::
* MESSAGE PROPERTIES::
* SEE ALSO::


File: notmuch-properties.info,  Node: SYNOPSIS,  Next: DESCRIPTION,  Prev: Top,  Up: Top

1 SYNOPSIS
**********

`notmuch' `count' `property:'<`key'>=<`value'>

`notmuch' `search' `property:'<`key'>=<`value'>

`notmuch' `show' `property:'<`key'>=<`value'>

`notmuch' `reindex' `property:'<`key'>=<`value'>

`notmuch' `tag' +<`tag'> `property:'<`key'>=<`value'>

`notmuch' `dump' `-include=properties'

`notmuch' `restore' `-include=properties'


File: notmuch-properties.info,  Node: DESCRIPTION,  Next: CONVENTIONS,  Prev: SYNOPSIS,  Up: Top

2 DESCRIPTION
*************

Several notmuch commands can search for, modify, add or remove
properties associated with specific messages.  Properties are key/value
pairs, and a message can have more than one key/value pair for the same
key.

While users can select based on a specific property in their search
terms with the prefix `property:', the notmuch command-line interface
does not provide mechanisms for modifying properties directly to the
user.

Instead, message properties are expected to be set and used
programmatically, according to logic in notmuch itself, or in
extensions to it.

Extensions to notmuch which make use of properties are encouraged to
report the specific properties used to the upstream notmuch project, as
a way of avoiding collisions in the property namespace.


File: notmuch-properties.info,  Node: CONVENTIONS,  Next: MESSAGE PROPERTIES,  Prev: DESCRIPTION,  Up: Top

3 CONVENTIONS
*************

Any property with a key that starts with "index." will be removed (and
possibly re-set) upon reindexing (see `notmuch-reindex(1)').


File: notmuch-properties.info,  Node: MESSAGE PROPERTIES,  Next: SEE ALSO,  Prev: CONVENTIONS,  Up: Top

4 MESSAGE PROPERTIES
********************

The following properties are set by notmuch internally in the course of
its normal activity.

`index.decryption'
     If a message contains encrypted content, and notmuch tries to
     decrypt that content during indexing, it will add the property
     `index.decryption=success' when the cleartext was successfully
     indexed.  If notmuch attempts to decrypt any part of a message
     during indexing and that decryption attempt fails, it will add the
     property `index.decryption=failure' to the message.

     Note that it's possible for a single message to have both
     `index.decryption=success' and `index.decryption=failure'.
     Consider an encrypted e-mail message that contains another
     encrypted e-mail message as an attachment - if the outer message
     can be decrypted, but the attached part cannot, then both
     properties will be set on the message as a whole.

     If notmuch never tried to decrypt an encrypted message during
     indexing (which is the default, see `index.decrypt' in
     `notmuch-config(1)'), then this property will not be set on that
     message.

`session-key'

     When `notmuch-show(1)' or `nomtuch-reply' encounters a message
     with an encrypted part, if notmuch finds a `session-key' property
     associated with the message, it will try that stashed session key
     for decryption.

     If you do not want to use any stashed session keys that might be
     present, you should pass those programs `--decrypt=false'.

     Using a stashed session key with "notmuch show" will speed up
     rendering of long encrypted threads.  It also allows the user to
     destroy the secret part of any expired encryption-capable subkey
     while still being able to read any retained messages for which
     they have stashed the session key.  This enables truly deletable
     e-mail, since (once the session key and asymmetric subkey are both
     destroyed) there are no keys left that can be used to decrypt any
     copy of the original message previously stored by an adversary.

     However, access to the stashed session key for an encrypted message
     permits full byte-for-byte reconstruction of the cleartext
     message.  This includes attachments, cryptographic signatures, and
     other material that cannot be reconstructed from the index alone.

     See `index.decrypt' in `notmuch-config(1)' for more details about
     how to set notmuch's policy on when to store session keys.

     The session key should be in the ASCII text form produced by
     GnuPG.  For OpenPGP, that consists of a decimal representation of
     the hash algorithm used (identified by number from RFC 4880, e.g.
     9 means AES-256) followed by a colon, followed by a hexadecimal
     representation of the algorithm-specific key.  For example, an
     AES-128 key might be stashed in a notmuch property as:
     `session-key=7:14B16AF65536C28AF209828DFE34C9E0'.

`index.repaired'

     Some messages arrive in forms that are confusing to view; they can
     be mangled by mail transport agents, or the sending mail user
     agent may structure them in a way that is confusing.  If notmuch
     knows how to both detect and repair such a problematic message, it
     will do so during indexing.

     If it applies a message repair during indexing, it will use the
     `index.repaired' property to note the type of repair(s) it
     performed.

     `index.repaired=skip-protected-headers-legacy-display' indicates
     that when indexing the cleartext of an encrypted message, notmuch
     skipped over a "legacy-display" text/rfc822-headers part that it
     found in that message, since it was able to index the built-in
     protected headers directly.

     `index.repaired=mixedup' indicates the repair of a "Mixed Up"
     encrypted PGP/MIME message, a mangling typically produced by
     Microsoft's Exchange MTA.  See
     <https://tools.ietf.org/html/draft-dkg-openpgp-pgpmime-message-mangling>
     for more information.


File: notmuch-properties.info,  Node: SEE ALSO,  Prev: MESSAGE PROPERTIES,  Up: Top

5 SEE ALSO
**********

`notmuch(1)', `notmuch-config(1)', `notmuch-dump(1)',
`notmuch-insert(1)', `notmuch-new(1)', `notmuch-reindex(1)',
`notmuch-reply(1)', `notmuch-restore(1)', `notmuch-show(1)',
`*notmuch-search-terms(7)'



Tag Table:
Node: Top424
Ref: man7/notmuch-properties doc689
Ref: 0689
Node: SYNOPSIS780
Ref: man7/notmuch-properties synopsis872
Ref: 1872
Ref: man7/notmuch-properties notmuch-properties872
Ref: 2872
Node: DESCRIPTION1227
Ref: man7/notmuch-properties description1327
Ref: 31327
Node: CONVENTIONS2122
Ref: man7/notmuch-properties conventions2232
Ref: 42232
Node: MESSAGE PROPERTIES2394
Ref: man7/notmuch-properties message-properties2501
Ref: 52501
Node: SEE ALSO6539
Ref: man7/notmuch-properties see-also6626
Ref: 66626

End Tag Table
