Using scripts to filter emails

See also:
Overview of scripting in Email Parser
Combining multiple filters
Using regular expressions in email filtering

What is an email filter?

In Email Parser, an email filter is a set of rules that determine whether an incoming email should continue through the workflow or be discarded. This is useful when your email account receives a mix of emails but you only want to process certain ones. For example, if you are parsing bank notifications, you would configure a filter so that only the bank notification emails go through the workflow. Any other email that does not match the filter criteria is simply skipped.

Email Parser provides several built-in ways to filter emails, such as matching by subject, sender, or keywords in the email body. You can also combine multiple filters or use regular expressions for more advanced matching.

When do you need a script-based filter?

Most of the time, the built-in filtering options are more than enough. You can filter emails by subject, sender address, or specific words in the email body without writing any code. However, there are cases where the kind of email you want to process is not easily identifiable by simple criteria. If you need more complex logic to decide whether an email should be processed or discarded, writing a small script is a great approach.

For advanced users (or users willing to use an AI assistant to help write some code), Email Parser supports filtering emails using JavaScript or C# code.

Filtering emails with JavaScript

To use JavaScript for filtering emails, open the filter settings and activate the checkbox “Filter email with the following Javascript code”. You will see a text area where you can write your script. You need to implement the function FilterEmail(), which receives an email parameter. This email object contains the email’s properties as public fields. For example, email.subject is a string with the email subject, email.from contains the sender address, and email.body has the email body text.

The function must return true to accept the email (it will continue through the workflow) or false to reject it (it will be discarded).

Here is an example of a JavaScript filter that accepts only emails from a specific sender with no attachments:

// FilterEmail: simple filter that accepts only emails from alerts@acmebank.com with no attachments.
// Returning true means the email is accepted (processed further); returning false means it is discarded.
function FilterEmail(email)
{
	// Extract sender address (use empty string if missing)
	let sender = email.from || "";

	// Ensure attachments is an array (use empty array if missing)
	let attachments = email.attachments || [];

	// Log basic information for debugging
	console.log("The email has " + attachments.length + " attachments");
	console.log("The email was sent from " + sender);

	// List top-level property names of the email object to the console
	console.log("Email object properties:");
	for (let prop in email) {
		if (Object.prototype.hasOwnProperty.call(email, prop)) console.log(prop);
	}

	// Decision logic:
	// - Returning true: the filter accepts the email (it will be processed further)
	// - Returning false: the filter rejects/discards the email (it will be skipped)
	// This filter accepts only emails that:
	//   1) have zero attachments (attachments.length === 0) AND
	//   2) have a sender address that contains "alerts@acmebank.com"
	// Any email not meeting both conditions will be rejected.
	return (attachments.length === 0 && sender.indexOf("alerts@acmebank.com") >= 0);
}

As you can see in the example, you can use console.log() to print messages that help you debug your filter logic. The script also demonstrates how to iterate over the properties of the email object, which is useful for discovering what fields are available.

The code editor built into Email Parser is intentionally minimal. It is meant as a place to paste your finished script, not for writing or debugging code. The recommended workflow is to copy the example code that Email Parser gives you into a proper code editor, develop and test your script there, and once it is working, copy it back into Email Parser. For JavaScript development, Visual Studio Code and WebStorm are excellent choices. For quick tests without installing anything, online tools like JsFiddle and CodePen are very handy.

Filtering emails with C#

Important: Using C# for filtering emails is only supported in the Windows application. The web app only supports JavaScript for email filtering.

To use C# for filtering, activate the checkbox “Filter email with the following C# code” in the filter settings. You need to implement the method FilterEmail() inside a public class called MyEmailFilter that derives from the ScriptBasedEmailFilter class. The FilterEmail() method receives a standard System.Net.Mail.MailMessage object as a parameter.

Just like with JavaScript, the method must return true to accept the email or false to reject it.

Here is an example of a C# filter that accepts only emails containing at least one PDF attachment:

using EmailParserBackend.ScriptingInterface;
using System.Net.Mail;

public class MyEmailFilter : ScriptBasedEmailFilter
{
    public override bool FilterEmail(MailMessage email)
    {
        // Example: pass only emails that have at least one PDF attachment
        foreach (Attachment attachment in email.Attachments)
        {
            if (attachment.Name.EndsWith(".pdf", System.StringComparison.OrdinalIgnoreCase))
                return true;
        }
        return false;
    }
}

In this example, the filter iterates over all attachments in the email. If any attachment has a .pdf extension, the email is accepted. Otherwise, it is rejected. Since you have access to the full MailMessage object, you can inspect any property of the email (subject, body, headers, attachments, etc.) to build your filtering logic.

As with JavaScript, the code editor inside Email Parser is not the best place to write or test your C# code. The recommended approach is to copy the example code into a proper development environment, build and test your filter there, and paste the finished code back into Email Parser. Visual Studio and Visual Studio Code are the most popular choices for C# development. If you prefer not to install anything, online tools such as .NET Fiddle and SharpLab let you write and run C# code directly in your browser.

Seeing the script-based filter in action

Once you have configured your script-based filter, Email Parser will evaluate each incoming email using your code. The screenshot below shows how email filtering with a script works in practice. You can see that emails matching the filter criteria are processed, while emails that do not match are discarded.