Why you probably don't want to use claws-mail

I've been using claws-mail as my email client for a while. Today I wanted to search all of my messages for some text and look through the results. When I couldn't figure out how to do that even after consulting the claws manual, I went to their official IRC channel.

For reference, here are some screenshots of the dialogs in question: claws-esearch-information-mtsucks.pngclaws-esearch-edit.png

This is what happened:

17:55 -!- .join mauke!~mauke@p3m/member/mauke #claws
17:55 -!- Irssi: #claws: Total of 33 nicks [8 ops, 0 halfops, 0 voices, 25 normal]
17:55 -!- Irssi: Join to #claws was synced in 1 secs
17:55 <mauke> hello, I am raging at claws-mail
18:08 <mauke> basically, the search feature is undocumented and I
              can't figure out how it works
18:15 <mohaa> "undocumented" ?
18:16 <mauke> yeah, like:  When in "Extended" mode, the "Information"
              button is visible, enabling you to see the search
18:17 <mauke> doesn't "enable" shit
18:17 <mauke> "Run on select" isn't even mentioned in the manual
18:17 <mauke> what is 'S' in the Information window?
18:18 <mauke> after I run a search, where are the results?
18:18 <mauke> what exactly does 'E' do and how is it useful?
18:19 <mauke> what is the unit of '#' in 'ag'?
18:19 <mauke> how is % supposed to be used?
18:19 <mauke> "all filtering expressions are allowed" - what are
              "filtering expressions" and what does "allowed" mean
18:20 <mauke> how is E different from X?
18:20 <mauke> are parens allowed? if not, how do expressions work?
18:21 <mauke> what's the unit of # in Se/Sg/Ss?
18:21 <mauke> why does the description of 'tg' ("messages which tags
              contain S") randomly use "which" instead of "whose"?
18:22 <mauke> how does 'k' work?
18:22 <mauke> are the colors numbers?
18:24 <mohaa> "parens" ?
18:24 <mauke> yes
18:25 -!- .join krayon!~fallen@pdpc/supporter/28for7/krayon #claws
18:25 <mauke> I mean, how else does grouping work?
18:47 -!- .join andyrtr_laptop!~andyrtr@f053200240.adsl.alicedsl.de #claws
19:12 -!- .quit andyrtr!~andyrtr@archlinux/developer/andyrtr [Quit: Ex-Chat]
19:22 -!- .join Columbo0815!~foobar@HSI-KBW-085-216-116-089.hsi.kabelbw.de #claws
19:24 -!- .join claws_!~claws@5ad1377a.bb.sky.com #claws
19:24 -!- .mode clunker3 #claws [+o claws_]
19:25 -!- .nick claws_ -> claws
19:42 -!- .quit Columbo0815!~foobar@HSI-KBW-085-216-116-089.hsi.kabelbw.de [Quit: Verlassend]
19:43 <@claws> mauke: you're funny :)
19:44 <mauke> why?
19:45 <@claws> maybe you wouldn't rage so much if you'd never found
               the feature or the feature didn't exist
19:45 <mauke> no, my main problem is the lack of a good search feature
19:45 <mauke> that's how this all started
19:45 <@claws> anyway, ignore the information dialog and click the
               edit button - this is probably easier to digest
19:46 <mauke> no, the edit button seems to lack all features
19:46 <@claws> the quick search is a _very good_ search feature imo
19:46 <@claws> no, the edit button does not
19:46 <mauke> claws: yes, but I can't figure out how to use it
19:46 <mauke> see above
19:46 <@claws> have you worked out how to use Filtering in Claws?
19:46 <mauke> no
19:46 <@claws> heh, thought not
19:47 <mauke> btw, I blanked some spam pages in the wiki
19:47 <@claws> heh, yes. there are always new spam pages in the wiki
19:47 <@claws> thanks. saved me a job
19:48 <@claws> back to the quick search, what are you likely to want
               to search for?
19:48 <mauke> text
19:48 <mauke> I want a full text search over everything
19:48 <@claws> b 'my search term' in Extended mode
19:48 <@claws> b is for body
19:48 <mauke> what happens if I omit the quotes?
19:49 <mauke> what happens with double quotes?
19:49 <mauke> how do I search for '?
19:49 <@claws> the quickest way to find your answer is to try it
19:50 <mauke> I did, results make no sense
19:50 <@claws> is that possible, perhaps?
19:50 <@claws> made no sense? in what way?
19:50 <mauke> why can't I just read a reference manual?
19:50 <@claws> dunno ...because you wouldn't??
19:50 <mauke> well, first there's problem #1: <mauke> after I run a
              search, where are the results?
19:51 <@claws> because you haven't written it yet?
19:51 <@claws> the results are in the msg list - this list is
               shortened, based on the results
19:51 <mauke> what msg list?
19:51 <@claws> that's quite obvious, i think, no???
19:51 <mauke> I have a nested folder structure
19:51 <@claws> now, m[e]s[sa]ge list _is_ in the manual!!
19:52 <@claws> the message list is not the folder list
19:52 <mauke> message list is the contents of one folder
19:52 <mauke> this is useless
19:52 <mauke> I don't want to manually click through all folders just
              to see if one of them maybe contains some search results
19:53 <@claws> then search in the top-level folder and use a recursive
19:53 <mauke> I did
19:53 <@claws> that's not useless
19:53 <mauke> where are my results?
19:54 <@claws> a folder which has results has its folder icon replaced
               with a magnifying glass. select that folder and you'll
               see your results
19:54 <mauke> so I still have to manually click through the folders?
19:54 <mauke> blargh
19:54 <mauke> who came up with this UI
19:54 <@claws> why do you ask?
19:55 <mauke> that was more of a rhetorical question
19:55 <@claws> more like a rude question, methinks
19:55 <mauke> the search seems to ignore everything after the first
19:55 <@claws> then quote
19:55 <mauke> is that correct?
19:56 <@claws> doesn't a test answer your question?
19:56 <mauke> no
19:56 <mauke> I can't rule out that it has some effect I didn't notice
19:57 <mauke> hence "seems to ignore"
19:57 <@claws> is it me, but you seem to have an attitude??
19:58 <mauke> I do, but not where you think
19:58 <mauke> this confuses me a bit
19:59 <@claws> you do, but not where i think?? that confuses me
19:59 <mauke> I've been trying to be nice and civil at the end there
19:59 <@claws> maybe the beginning would have been better, but
19:59 <@claws> the quick search is good, it works. maybe it doesn't
               work how you want it to work, but there it is
20:00 <mauke> my main problem is not that it doesn't work how I want
              it to, it's that it's not documented
20:00 <mauke> so I don't even know if it does what I want
20:01 <mauke> the list at the beginning is the "obvious" questions I
              had when I saw the [Information] window
20:01 <mauke> the [Edit] dialog doesn't seem to allow a full text
20:02 <mauke> and I didn't notice the folder icon change at all
20:02 <mauke> what I find weird is that you can't give me a straight
              answer as to what "b x y z" does
20:03 <mauke> normally I'd expect "RTFM" in response to that but there
              doesn't seem to be a FM
20:03 <mauke> you said I should try it; I did. now I'm simply asking
              for confirmation
20:04 <mauke> and all I get is "you seem to have an attitude"
20:08 <@claws> in the edit dialogue use phrase --> in body part
20:08 <mauke> oh wow
20:09 <@claws> maybe that's "all" you get because that's "all" you
               gave?? :)
20:09 <mauke> I didn't even think to look there because Header, Age,
              Flags, ... are other top-level categories
20:09 <@claws> in this case it's not RTFM, it's WTFM :)
20:10 <mauke> so I in analogy to Header I was looking for Body or
              Message or whatever
20:10 <mauke> yeah, Phrase is the odd one out
20:10 <mauke> the other items specify which part/attribute of the
              message to search *in*; Phrase describes what kind of
              thing you're looking *for*
20:11 <mauke> claws: dude, I asked you a simple yes/no question
20:11 <mauke> you could answer 1) yes, 2) no, 3) rtfm at ...,
              4) you're stupid because ...
20:12 <@claws> but none of those fitted my answer
20:12 <mauke> but this "I don't like your attitude" bullshit is
              extremely annoying
20:12 <@claws> yep, i thought the same
20:12 <mauke> so why are you doing it?
20:13 <@claws> i'm not any more, i'm going to do something else
20:13 <mauke> sorry for assuming this program was meant to have users

Update 1:

  • Changed the title from "shouldn't" to "don't want to" because that's closer to what I meant.
  • Reformatted the log a bit to prevent the right side being cut off.

Update 2:

Oh wow, it keeps getting better. I really wanted to know how this #!$@ actually works so I downloaded the source code. It comes with a fairly long README that (among other things) explains Quick Search better than both the "user manual" and the built-in help system. It even has examples! First the filter engine syntax:

    from regexpcase "foo"
    subject regexp "Bug" & to regexp "claws-mail"

Then the extended patterns:

    # means number
    S means regexp string
    f "john beavis"    messages from john beavis
    %f "John Beavis"   messages from John Beavis (case sensitive)
    ~s foo             messages which do not have foo in the subject
    f foo & ~s bar     messages from foo that do not have bar in thesubject

Still missing:

  • What units are the # numbers in?
  • What's the syntax for a "regexp string"?
  • What regexp flavor?

But it does show that you can use double quotes and that the % should be placed immediately in front of one of the string operators.

(BTW, "S means regexp string" is the only occurrence of "regex" or "regul.*ex" in README, doc/, or manual/.)


Now I've looked at the source code. Turns out claws-mail uses a rewriting system to convert "extended patterns" into "filter syntax" internally. The actual syntax is a bit complicated:

  • Tokens in the search expression are space separated.
  • Every term in the expression starts with an (optionally prefixed) command.
  • The prefixes are !, ~ and %.
  • You can have at most one of ! and ~ (both mean "not"). If you have one, it must appear first.
  • You can also have % (it means "case sensitive").
  • If prefixes are present, they must appear in the above order with no whitespace in between (example: !%f).
  • Then comes the command code.
  • Then the argument (if the command takes one).
  • If the argument starts with a " (double quote), it ends at the next ". There is no way to embed a " in the string. Otherwise it ends at the next ' ' (space, ASCII 32) character (not the next whitespace character!).
  • As far as the rewriter is concerned, & and | are just commands without arguments, not operators between commands. That means there's no way to nest them (it also means ~& is accepted).

Regarding regex syntax:

  • It uses regcomp from regex.h with the REG_EXTENDED flag, so the flavor is POSIX Extended.

Regarding numeric units:

  • Colors are something terrible (a message's "color value" is an integer whose parts are stored in different places; requires bitwise operations to reassemble). I'm just going to assume that colors are numbered according to their appearance in the Message > Color label submenu.
  • Age is internally stored with a resolution of one second, but the search operators work in whole days.
  • Size is the raw message size in bytes.


If you're an end user, claws-mail may not be for you. Source diving seems to be the best way to get accurate and complete information on how the program works.


You didn’t exactly help foster a productive exchange. You came in there essentially asking “wtf is this crap?!” – even if you have a point (which I do think you did in this case), people won’t be inclined to help you out when you start off on that foot…

That said, never having used or seen Claws myself, based on how I understand it from just the chat log excerpt, its search feature seems to be a design-by-programmer (“I can already show folders, so I’ll just have search narrow their contents – no need to implement one-off display logic and UI for the search results”). That does not bode well for its interaction design in general.

Again, it sounds like design-by-programmer. I don’t disagree with your complaints.

The thing is, the people who wrote a program or have been using it for a long time, no matter how inept its design, will always believe it is quite obvious and easy to use. If you barge in there with a barrage of questions, it’s liable to make you look dumb to them. It doesn’t mean you are dumb, but from their perspective it looks that way. And then the slightest show of annoyance or general attitude will invariably look like a show of entitlement of some sort.

That’s not how it should rationally play out, but it’s human nature.

If you manage a sufficient consistent display of humility you may be able to make the barrage-of-questions approach work in your favour, but otherwise it’s a better idea to engage them gradually before you open the floodgates, not storm in firing from all barrels. That’s only liable to make them duck and fire back from the embrasures.

Related: Love your idiots.

Hi mauke. I agree with Aristotle here - your tone in the dialogue you quoted was far too rude. Arguably, I may have erred in this respect as well when I was in a bad mood, but from my experience, you can achieve more by being friendly, courteous, respectful and less demanding.

I'm not going to stop using claws-mail just because its search facilities are underdocumented, because its search is only part of its general functionality and should not be hard to replace with an external program (given enough time, research and know-how).

Holy Moly!

Sorry to say that but both of you act like assholes and i am not sure who is to blame more?

The user entering the channel trolling around or the op responding accordingly?

Well lets get constructive shall we?
I too use Claws Mail (under Windows). To be honest nearly all E-Mail Clients suck. Someone said once about Claws Mail "it just sucks less than others" and i think that's right. Its flawed in some ways. Like:
* Why can't i access my mails while its fetching new ones?
* The search of course! I too would like to see a simple "Search Body" similar to subject and additionally a "Search whole mail". In fact i stumbled upon this post because i was searching for this "AGAIN"!
* Few important features are missing in Windows (they are not ported - probably wont be) :/
* Address-book is a disaster! Why can't i open a contact inside a group? It seems like they intended them only for mailing but not for editing. Btw click2dial missing here as well :/

Its somewhat a shame because the developers seem to have the knowledge to build this client but yet fail to deliver a friendly App but instead build a programmatic App.

I wouldn't mind that if you could build on top a wrapper that was using this programmatic approach and deliver a friendly GUI instead.

Frankly i still think Claws is one of the better Clients. I don't want to use Outlook it completely changes with each iteration and they don't care about removing previous features.
I neither like Thunderbird its slow and PGP implementation is horribly done.

I made a few tickets at Claws site and i must say they were friendly to me and helped me so i can't blame them about that.


I never heard of claws mail until today, I did a quick search to gather some info and this page was in the first results.

The IRC logs imply a blatant mistake, if not a perverse evil intent, on the maintainers' part for not documenting what is without doubt an essential function of a mail software that aims to be user-friendly. But, as anyone who has ever done useful work to the society knows, when a maintainer and a user have a heated argument, typically it's the user who has a problem. So, inspired by your post, I decided to try claws mail out to decide whether it is worth my time or not.

Sir, with the manual in front of me, literally less than 30 seconds passwd between the moment I clicked the Extended checkbox for the first time in my life, to the moment I knew how to master the search syntax. No programming knowledge is required.

And yes, I'm not going to help someone who is unable to follow guidance from upstream or at least cooperate with them, because I dream of a better world where people don't troll at volunteers.

Leave a comment

About mauke

user-pic I blog about Perl.