Question

where do I begin?

I can’t seem to find any definitive documentation. (I am probably looking in the wrong places….).

I want to be able to edit IMAP keywords (for tagging purposes) for email messages.

I have some really noobie questions;
how are they added?
are keywords applied directly to message headers (if so, what is the syntax), or is there some other kind of imap voodoo at work…

thanks in advance.

Answer 1

IMAP custom keywords are applied to messages via the STORE command. Once added, they’ll be returned when you do a FETCH for FLAGS and they’ll be searchable via SEARCH KEYWORD:

A001 FETCH 5 (UID RFC822.SIZE FLAGS)
* 5 FETCH (UID 292 RFC822.SIZE 2554 FLAGS (\Seen))
A001 OK FETCH completed

A002 STORE 5 +FLAGS (pending ignored uninteresting)
* 5 FETCH (FLAGS (\Seen pending ignored uninteresting))
A002 OK STORE completed

A003 FETCH 5 (UID RFC822.SIZE FLAGS)
* 5 FETCH (UID 292 RFC822.SIZE 2554 FLAGS (\Seen pending ignored uninteresting))
A003 OK FETCH completed

A004 SEARCH KEYWORD pending
* SEARCH 5
A004 OK SEARCH completed

Note that when you create a new keyword via STORE, the server should respond with an updated list of all the system and user flags defined on the mailbox:

A002 STORE 5 +FLAGS (pending ignored uninteresting)
* FLAGS (\Answered \Deleted \Draft \Flagged \Seen pending ignored uninteresting)
* 5 FETCH (FLAGS (pending ignored uninteresting))
A002 OK STORE completed

Some servers won’t allow you to create used-defined keywords. They’ll let you know this by not including \* at the end of the PERMANENTFLAGS list when you SELECT the mailbox.

The STORE command allows you to add keywords to a message’s existing set (via +FLAGS), remove them (-FLAGS), or replace the set with an entirely new set (FLAGS).