On this Page

• Introduction
• How do filters work?
• How do I setup a filter?
  • Adding Extra Headers?
  • Adding Leading and Trailing Spaces to Patterns
  • Setting a pattern to NOT to match
  • Applying more than One Filter
  • Using External Commands on Filters
  • The Folders Section
  • The Status Section
• List of Typical Mistakes
• Examples

Introduction

In a few words, a filter in Pine is a mechanism of selecting mail based on text that the message contains, status (New, Answered, etc), and folder (which folder the message is in).

Filters give you the ability to split your mail into different folders, in this way you can keep different types of mail in different places. For example, I filter my mail so that only personal mail ends in my INBOX, all messages from mailing lists are filtered into different folders, each folder contains only messages received from that particular list. In that way I can

1. Distinguish easily what my personal mail is.
2. Check easily when new mail has arrived from a particular mailing list.

Another use of filters is deleting unwanted e-mail (like spam), or using it like a killfile in news.

How do filters work?

Every time Pine opens a folder, for each message in the folder it will scan to check if any of the filters apply to the message, if it does it will execute it and move on to the next message, where the cycle will repeat again. Filters are also executed every time that new mail arrives to the folder (if the folder is already opened), or if the filter depended on its status (message is new, answered), when the folder is about to be closed.

Every filter has two parts, the conditions that activate the filter (e.g. the message is from your boss) and the action to be taken if the conditions are satisfied (e.g. move it to the folder "work").

When you want to define a filter, you must remember that the filter will be activated if all the conditions that you specify are satisfied.

For versions of Pine previous to 4.50, if a message satisfies all the conditions, there will be just one action. Starting with Pine4.50, you can make Pine act as many filters are you like on the same message, as long as all the conditions in the filter match the message. A complete explanation of this feature is given below. If the conditions of a filter match a particular message, you can use the filter to either, delete the message or save it to a folder of your choice.

There is a further interesting consideration about filtering mail, which you need to be aware of, and is the fact that the message that you filter from a folder is not expunged from the folder after it was filtered. The message will be expunged when the folder is closed. This is not intuitive, because when you open the folder you will have the impression that the message is not in the folder anymore, but believe it or not, it is there. It was just marked "hidden" from your view. A message is set with the delete flag only when it's saved to another folder.

It is important to notice that this "hidden" flag that a filtered message has, is set after the message has been filtered. This may trigger a bug, which occurs when two sessions of Pine are trying to apply the same filter to a message. Under certain circumstances a message could be filtered more than once to another folder. At this time this problem does not have a solution.

Another important fact which you should not forget is that creating filters with long patterns may make the filter fail. This is because the UW-IMAP server has a limit of 50 levels of depth for a search program, which means in practice that you can not add more than 25 addresses in the From field (this may not be true for other servers, however). Notice, also, that there's no such limit for local folders, which means that you can add as many parameters as you like to your filters for local folders.

How Do I Set up a Filter?

To get to the filters setup screen you must press M S R F, you have two options essentially, you can press ?, and read help on how to set up filters or press A to add a filter. Remember to give a good nickname to each filter that you create so that you can go back to them afterwards if changes are necessary in the future.

This is the part that confuses most of the people, so before you begin you need to know a few things.

When you start this section you will see several lines that look like
 

If you put the cursor in anyone of them and press RETURN several times you will see that this text will toggle between:
 

• <No Value Set> means that you do not care about the value that this particular header has, or if this header is (or not) present in the headers of the message being filtered. It is considered a pattern match.
   
  
• <Empty Value> means that there is a header with the specified name, but you do not care about its value. For example the condition Cc pattern = <Empty Value>, means that there is a Cc: header in the message that you intend to filter.

There is a complete explanation of how to set these conditions in the To Pattern, which you can get by putting the cursor over that line and press the ? key. It is also worth noticing that the ^T command is available for many of these headers. You can read about the importance of this command here.

Notice that a difference between setting filters, and roles or scores is that you need to define at least one condition in order for the filter to be executed. In the case of filters this may be confusing, since it is considered that not defining a pattern is always a pattern match. The reason why you need to define a pattern for filtering is because filtering is a potentially destructive operation, you may delete more e-mail than you intended, so it's a protection measure.

There are also some special patterns that you should know before you start adding filters, they are the Recipient, Participation, AllText Age Interval and Score pattern. Here are their meanings and why you would like (or not like) to use them.
 

• The Recipient (actually called Recip Pattern), should contain one or several e-mail address. It is considered a pattern match if the address entered there appears either in the To: or the Cc: field. The reason why this pattern is important is because it saves you the time to write two filters, one where the e-mail address appears in the To: field, and another where the e-mail address appears in the Cc: field (See the section on typical mistakes).
   
  
• The Participation (actually called Partic Pattern), is very similar to the Recipient pattern, as it includes a match for the content of the To: and Cc: fields. The only real difference is that it also includes the From: field. The same considerations that I wrote in the Recipient pattern apply to this pattern too.
   
  
• The AllText pattern, should contain any string that you like, and it will be considered a match if that string is found anywhere in the message, both the headers and the text of the message. Notice that search is case insensitive, which means that searching for "Fred", "FRED, "fred", etc will not make any difference in the final result.
   
  The technical part of this header starts when you need to enter text that is not in the US-ASCII character set, say text like "el niņo". In that case, since "ņ" is not a US-ASCII character, the search will be done in the character set that is specified in your character-set configuration option. This means that if you add some text in some character set, you should make sure that this is the character set that you have set in your character-set variable.
   
  See the information on Search for a more complete discussion on this command.
   
  
• The Age Interval is used to indicate how long ago was the message originally sent. For example, you can filter messages that have been 30 days in the folder to be deleted, or moved to some other folder. All you need to write in this field is an interval of the form (min, max), where min the minimum number of days that the message has been in the folder and max is the maximum number of days that the message has been in the folder. Observe that the interval includes the end points. If you set max to be INF pine will filter all messages that have been in the folder for at least min days.
   
  Observe that there are two possible ways to compute this interval. On the one hand one could use the date that the message was sent (which appears in the Date: header), or one could use the date that the message was saved to that folder (which is not visible in the message). You can decide which date to use by setting (or unsetting) the configuration option
   
  [  ] use-date-header-for-age,
   
  found at the bottom of each filter.
   
  
• The Score interval pattern is used to activate a filter if the score assigned to this message is in a certain interval. The default is that this will always be a pattern match.
   
  The way one usually think of this pattern, is that you set a score as a way to tell Pine that it needs to distinguish between mail sent by person A and mail sent by person B (something like, the message comes from one specific address or the subject contains a certain string). One usually uses this form of scoring not only for filtering but also for sorting.
   
  For versions of Pine previous to 4.50, you can also use this pattern to filter messages that do not match a criteria, instead of those that do match one. Here is the way to do it.
   
  Say that you know that there is a domain, say domain.org, from where you usually receive spam, but you have a friend in that domain, whose e-mail address is myfriend@domain.org, and you would like to delete all e-mail coming from that domain, except the one that comes from your friend using filters.
   
  What you can do is set a "score rule" that will give a message from your friend a score of 10, say, and set another score rule that will assign a score of -5 to any e-mail from "domain.org". The result of this is that if the mail is from your friend then it will get a score of 5 (10 + -5), but any other e-mail from anyone else in that domain will get a score of -5. Now you can set the score pattern to delete any e-mail message that has a score of -5. In this way you will have filtered away messages from that domain. If a message comes from another domain, that is not affected by any of your score rules, it will not be affected either by this filter rule.
   
  

Score interval    = (-INF,INF)

Adding Extra Headers

Starting with version 4.50 you can filter a message based on any header present in the message. One use of this is when you use a filter on your e-mail that adds headers that show the result of the filter. A typical case when this happens is when one uses filters to detect spam.

If you would like to filter based on a header not in the list of headers used by Pine, you must add it to the list of header first. In order to do so, put the cursor over

Add Extra Headers

and press X. You will be asked to enter the name of the header. Say you wanted to add the extra header X-Extra-Header, then after entering the name of that header, Pine will add a line to the list of headers reading X-Extra-Header Pattern = <No Value Set>, to which you will need to add the value that you want to filter, using the above stated rules.

Adding Leading and Trailing Spaces to Patterns

When you add a pattern, pine strips leading an trailing spaces from the definition of the pattern. This is undesirable if what you are trying to match depends on these spaces. For example, you can't just add a pattern that matches 3 consecutive spaces.

This problem can be avoided if one uses another notation for these spaces. For example, say that you need your pattern to match the word example followed by three spaces, then instead of writing example   , which Pine will truncate to example, you should write =?us-ascii?Q?example___?=. Each underline character _ represents a space. This form of writing a space works well when there are no 8-bit characters. If you intend to add an 8-bit character, you must encode it in some other character set, like iso-8859-1 or utf-8, and the encoding of those characters must be used. There is a restriction of 75 characters in the encoding, so don't make your matches too long.

Setting a pattern to NOT to match

! From Pattern = Wilma Flinstone

! Cc Pattern = <Empty Value> 

! Cc Pattern = <No Value Set> 

Cc Pattern = <No Value Set> 

Applying More than One Filter

It is sometimes convenient to apply more than one filter to a message. For example, one could use a filter to move a message to two different folders.

Normally after Pine has filtered a message, Pine will not execute any more filters on the message. If you need to tell Pine that you want to have more filters applied on the same message, you must enable the configuration option

at the bottom of the filter, so that Pine will continue searching for another filter that matches after it has found a message that matches this filter.

Using External Commands on Filters

You can have an external program analyze your message, and use this information to decide how you want to filter a message. A typical usage of this is to use an external program to determine if a message is spam. Other uses include tests on the message that Pine does not do (e.g. Pine does not test for the size of the message, or if a header exists and it is empty).

Pine includes three variables that control this. They are Command, Exit Status Interval and the Character Limit. Here's how they work

• The Command is the full path of the program in the same computer where Pine is running that is going to be used to analyze the message. Remember that all headers and body (including attachments) are passed to the program. If the program listed in this configuration option is not found, the rule is not a match.
   
  An interesting fact is that if the program has any type of output, it is not captured by Pine. In fact, it is lost, so if this output is discarded, how is Pine supposed to know what to do with the message? This leads us to...
   
  
• The Exit Status Interval is an interval of the form (a,b), where a and b are integers. In Pine and interval of the form (a,b) means all integers between a and b including a and b, so for example, (0, 0) is just the number 0, and (-1,2) is the set of numbers -1, 0, 1 and 2 (in math, the interval (a,b) does not contain a nor b, so this is not the mathematical notation for intervals).
   
  In case you are not aware of what the exit status of a program is, here is a brief explanation.
   
  Normally every program is called from some other program. The most basic call of one program to another is the operating system starting a program. The calling program is called the parent and the called program the child, this is because the process of the child was created by the parent. Normally parent and child will do their own thing, until the child has finished. When this happens, control returns to the parent. But what if the parent sent the child to do something for it, how does it know if the child was successful or not?. That is the point of the exit status. When the child ends, the child returns an exit status to the parent. Normally the parent knows how to interpret the exit status, so the communication between parent and child is complete. Most programs return an exit value of 0 (zero) when they have completed their tasks successfuly and some other number (either positive or negative) when they have failed, or something has gone wrong.
   
  For example, the spamassassin program can be called with the -e switch. When called this way, it exits with status 0 if the messages is not spam but non zero if it is.
   
  You can have a program exit with any exit status that you like, if you wrap the program in a script. This means that instead of calling the program directly (and checking its exit status), you can write a script that calls the program and then exit the script with your favorite exit status. If you do not know how to do this, do not worry, it is very easy
   
  
• The Character Limit variable indicates how many characters of a message should Pine take from the message so that the filter program can do its job. This is useful because some messages can be huge (e.g. if they contain attachments), so that processing them can be very slow and this is undesirable.
   
  There are some special values that this variable can have. The special value -1 means that the full message (headers and body) will be fed to the program (a bad idea), a value of 0 (zero) means that only the headers will be fed to the program, and any other possitive value means that the headers plus that many characters from the body will be fed to the filter.

You can read an explicit example on how one can use this method to filter messages.

The Folders Section

In this section you need to specify the folder over which the filter is supposed to act. There are several options, all of them self explanatory. The only non obvious part is how to fill the "Specific" field. If you need to filter from a specific newsgroup you should give the following syntax:

In essence, anything that is non local you must give a location in the format above, or if it's local I recommend to give the full path.

Do not check (*) Email and then enter a specific folder, this causes all Email folders to match.

The Status Section

You can filter a message based on its status, meaning, it's New, Answered, Important or Deleted. The meaning of each of these selections is very clear. The only pattern that may confuse you is the pattern for New message. Unfortunately, there is an inconsistency in the meaning of the word New, which may cause you some grief when setting up a filter.

In the default configuration of Pine, you will think that a message is New when it has the N in the index. If you have never changed the index-format in the index screen, then you will see a N flag on messages that are either new or have not been read, and they are referred by Pine as New messages. For example, if you read a message and want to set it to unread, you would flag it new again. Starting in version 4.50 a message that is new in this sense is called New (Unseen).

In versions previous to 4.50 a message was considered New in a filter if it was not present in the folder the last time this was opened. This includes messages that arrived when the folder was already opened as well as messages that arrived during the period of time that the folder was closed. Starting in version 4.50 a message that is new in this sense is called Recent.

Notice that at the bottom of the selection there is an option

This option was created in order to avoid a bug in which Pine would filter a message twice if, for example, the connection to the server was broken during the normal operation of Pine. In that case, the message was filtered for the second time when a new connection was created. Notice that even with this option enabled, messages can still be filtered twice, since if two sessions of Pine are accessing the INBOX, there's a small chance that this may happen. In any case, the likelihood of messages being filtered twice with this option enabled is very small, and you should set it.

List of Typical Mistakes

1. One of the most typical mistakes when adding filters is adding the same header to two (or more) header patterns, like To: and Cc:. This is a mistake usually because when somebody sends you a message, your e-mail address is in either the To: field or the Cc: field but not in both. If you intention was to set a filter that worked if your address was in the To: or the Cc: field, use the Recip Pattern as explained before. Also consider using the Partic Pattern for doing this task.
2. Another typical mistake is that it takes some time to figure out that for filtering a message from a newsgroup you need to write the name of the news server from which the message is going to be filtered. The syntax was explained before in the "folders" section.
3. Be careful when entering the data, once I intended to enter a period "." and entered a comma ",". In this form I realized later that I was filtering more messages than what I intended, so be careful in your input.
4. When specifying a folder in the Current Folder Type section, do not check (*) Email and then enter a specific folder, this causes all Email folders to match. In other words, the specific folder is ignored.
5. Remember that there is a distinction between <Empty Value> and <No value Set>. This is important as it may make the difference between the filter matching the message or not.

Examples

Here there is a link to examples of how to set up certain patterns. It is in some sense an expanded version of some of the information given here, but with much more additional information.
 

You are in Home > Filters