NOTMUCH-INSERT(1)

💖 NAME 💖

notmuch-insert — drop a message into your maildir and your notmuch database, all in one lil glow-up ✨

(btw this whole page is the notmuch-insert(1) manual, bestie, so you're in the right place 🫶)

---

🌸 SYNOPSIS 🌸

notmuch insert [option ...] [+<tag>|-<tag> ...]

---

🦋 DESCRIPTION 🦋

okay so here's the tea: notmuch insert reads a message from standard input and delivers it into the maildir directory that the config option database.mail_root points at <#nmconfig-database.mail_root>, and then it folds that message into the notmuch database. it's literally the alternative to running some separate delivery tool and then doing notmuch-new <#notmuch-new-1> afterwards like a peasant 💅

your shiny new message gets tagged with whatever new.tags <#nmconfig-new.tags> says, and then by whatever you do on the command line: tags with a + in front get added, tags with a - in front get removed. slay.

if the new message is a duplicate of something already in the database (same Message-ID, bestie, same soul), it still gets added to the maildir folder and the notmuch database — but the tags will not be changed. no touchy. 🙈

the insert command also supports hooks. go read notmuch-hooks <#notmuch-hooks-5> for all the details on those.

⚠️ real talk: option arguments must come before any tag operation arguments. no mixing, no chaos.

supported options for insert include:

• --folder=<folder> — deliver the message into the folder you name, relative to the top-level directory given by database.mail_root <#nmconfig-database.mail_root>. the default is the empty string, which means it just delivers to the top-level directory. simple. iconic. 🎀
• --create-folder — try to create the folder named by the --folder option if it doesn't exist yet. otherwise that folder has to already exist for mail delivery to succeed. no folder, no service 💀
• --keep — keep the message file if indexing fails, and keep the message indexed if applying tags or maildir flag synchronization fails. it ignores those errors and returns exit status 0 to say mail delivery succeeded. forgiving queen 👑
• --no-hooks — prevent hooks from being run. sometimes you just don't want the drama.
• --world-readable — when writing mail to the mailbox, let users other than the current user read it. note that this does not override umask. by default, delivered mail is only readable by the current user. (so yes, this is the "everyone can peek" button, use responsibly 🌈)
• --decrypt=(true|nostash|auto|false) — buckle up, this one's the main character:
  • if true and the message is encrypted, try to decrypt the message while indexing, and stash any session keys discovered along the way.
  • if auto, and notmuch already knows about a session key for the message, it'll try decrypting using that session key — but it will not try to access the user's secret keys.
  • if decryption is successful, index the cleartext itself.
  • either way, the message is always stored to disk in its original form (ciphertext). always. fr fr.
  • nostash is the same as true, except it will not stash newly-discovered session keys in the database.
  • be aware that the index is likely sufficient (and a stashed session key is certainly sufficient) to reconstruct the cleartext of the message itself, so please ensure that the notmuch message index is adequately protected. DO NOT USE --decrypt=true or --decrypt=nostash without considering the security of your index. 🔥 this is not a drill.
  • see also index.decrypt <#nmconfig-index.decrypt> in notmuch-config <#notmuch-config-1>.

---

💜 CONFIGURATION 💜

indexing is influenced by the config options index.decrypt <#nmconfig-index.decrypt> and index.header.<prefix> <#nmconfig-index.header.-prefix>. tagging is controlled by new.tags <#nmconfig-new.tags> and maildir.synchronize_flags <#nmconfig-maildir.synchronize_flags>. go check notmuch-config <#notmuch-config-1> for the details, bestie 📖

---

⭐ EXIT STATUS ⭐

this command returns exit status 0 on successful mail delivery, and non-zero otherwise. by default, any error means "mail delivery failed" — that includes message file delivery to the filesystem, message indexing to the Notmuch database, changing tags, and synchronizing tags to maildir flags. the --keep option is there if you wanna settle for "well, at least the message file landed". 🫶

this command supports the following special exit status code for errors most likely to be temporary in nature, e.g. failure to get a database write lock:

• 75 (EX_TEMPFAIL) — a temporary failure occurred; the user is invited to retry. take a breath, try again 💅

and heads up: the exit status of the post-insert hook does not affect the exit status of the insert command. not even a little.

---

🌈 SEE ALSO 🌈

notmuch <#notmuch-1>, notmuch-config <#notmuch-config-1>, notmuch-count <#notmuch-count-1>, notmuch-dump <#notmuch-dump-1>, notmuch-hooks <#notmuch-hooks-5>, notmuch-reply <#notmuch-reply-1>, notmuch-restore <#notmuch-restore-1>, notmuch-search <#notmuch-search-1>, notmuch-search-terms <#notmuch-search-terms-7>, notmuch-show <#notmuch-show-1>, notmuch-tag <#notmuch-tag-1>

---

🎀 Author 🎀

Carl Worth and many others 👑

💖 Copyright 💖

2009-2026, Carl Worth and many others

---

and that's the whole vibe check, bestie ✨ this page is from notmuch 0.40, dated Jan 31, 2026 — go forth and insert your mail, you absolute legend 🦋💅🌸