Raw Sieve Editor (Agency)

Most people will never need this page. The visual filter builder in TrekMail handles the vast majority of email filtering needs, and it is easier to use. But if you are a developer, an IT admin managing dozens of mailboxes, or a power user who has hit the limits of the visual builder, the raw Sieve editor gives you full control over how incoming mail is processed.

This feature is available exclusively on the Agency plan.

What is Sieve?

Sieve is a small scripting language designed specifically for filtering email. Think of it as a set of instructions that lives on the mail server and runs every time a new message arrives. It looks at the message -- who sent it, what the subject is, how big it is, what headers it has -- and then takes action based on your rules: move it to a folder, forward it, flag it, reject it, or auto-reply.

The key advantage of Sieve over client-side rules (the kind you set up in Outlook or Apple Mail) is that Sieve runs on the server. It works 24 hours a day, regardless of whether your computer is on or your email app is open. Every device that connects to your mailbox sees the same result.

You do not need to learn Sieve to use TrekMail effectively. The visual filter builder writes Sieve behind the scenes. The raw editor just lets you write it yourself when you need something the visual builder cannot do.

When to use raw Sieve vs. visual filters

Use the visual filter builder when:

• You need straightforward conditions like "from contains X" or "subject contains Y."
• You want to move, forward, flag, reject, or discard messages.
• You are not comfortable writing code.
• You want to make quick changes without worrying about syntax.

Use the raw Sieve editor when:

• You need complex conditional logic -- for example, "if this AND that, but NOT the other thing."
• You want to match patterns using regular expressions (like order numbers in a specific format).
• You need to combine vacation auto-replies with filtering and forwarding in a single script.
• You want to filter based on custom headers that the visual builder does not expose.
• You are managing templates that you copy across many mailboxes.

Where to find it

1. Open the TrekMail dashboard and go to Mailboxes.
2. Click Settings next to the mailbox you want to configure.
3. Select the Sieve tab.
4. You'll see a code editor with your current script (auto-generated from your visual filters). Edit it directly or write your own from scratch.
5. Click Save and activate to upload and apply the script.

The editor opens with your current script (or a blank canvas if no script exists yet). You can write or paste your script, then click Save and activate to apply it.

Supported extensions

Sieve is modular. The base language is simple, and extensions add extra capabilities. Here are the extensions TrekMail supports, explained in plain language:

To use an extension, you must declare it at the top of your script with a require statement. More on that below.

Example scripts

Here are four complete, commented scripts you can adapt for your own use.

Example 1: Complex conditional forwarding

Forward emails from a specific client that mention "proposal" in the subject and are smaller than 5 MB. File them into a project folder and flag them.

require ["fileinto", "copy", "imap4flags", "relational", "comparator-i;ascii-numeric"];

# Forward proposal emails from client, but only if they are under 5MB
if allof (
    address :contains "from" "@bigclient.com",
    header :contains "subject" "proposal",
    size :under 5M
) {
    # Send a copy to the project manager
    redirect :copy "pm@youragency.com";

    # Flag it for follow-up
    addflag "\\Flagged";

    # File it in the client folder
    fileinto "Clients/BigClient/Proposals";

    # Stop processing further rules
    stop;
}

# Everything else from this client goes to their general folder
if address :contains "from" "@bigclient.com" {
    fileinto "Clients/BigClient";
    stop;
}

What this does: The first rule is very specific -- it only matches emails from the client about proposals that are under 5 MB. Those get forwarded, flagged, and filed. The second rule is a catch-all for everything else from that client, filing it into a general folder.

Example 2: Regex matching for order numbers

Match emails that contain order numbers in a specific format (like ORD-12345 or ORD-98765) and file them automatically.

require ["fileinto", "regex"];

# Match order confirmation emails with order numbers like ORD-#####
if header :regex "subject" "ORD-[0-9]{4,6}" {
    fileinto "Orders";
    stop;
}

# Match support ticket numbers like TICKET-####
if header :regex "subject" "TICKET-[0-9]{3,}" {
    fileinto "Support Tickets";
    stop;
}

What this does: Regular expressions let you match patterns rather than exact text. [0-9]{4,6} means "between 4 and 6 digits." This catches ORD-1234, ORD-12345, and ORD-123456 without you having to list every possible order number.

Example 3: Combined vacation, filing, and forwarding

A single script that handles your out-of-office reply, forwards urgent messages to a colleague, and files everything else by category.

require ["fileinto", "vacation", "copy", "imap4flags"];

# Auto-reply to everyone (once per 3 days per sender)
vacation :days 3 :subject "Out of office until April 15"
    "Thanks for your email. I am out of the office until April 15
with limited access to email. For urgent matters, please contact
Sarah at sarah@youragency.com. I will reply when I return.";

# Forward urgent emails to Sarah immediately
if header :contains "subject" "urgent" {
    redirect :copy "sarah@youragency.com";
    addflag "\\Flagged";
}

# File invoices
if header :contains "subject" "invoice" {
    fileinto "Invoices";
    stop;
}

# File newsletters
if address :contains "from" "newsletter" {
    fileinto "Newsletters";
    stop;
}

What this does: The vacation command at the top runs for every incoming message and sends your auto-reply (at most once every 3 days per sender). Then the rest of the rules handle sorting. Notice that the vacation command does not use stop -- it sends the reply and then lets the script continue to the filing rules below it. This is how you combine auto-reply with other filters.

Example 4: Flagging by custom header

Some email systems add custom headers like X-Priority to indicate message importance. This script reads that header and flags high-priority messages.

require ["imap4flags", "fileinto", "relational", "comparator-i;ascii-numeric"];

# X-Priority: 1 = highest, 5 = lowest
# Flag messages marked as high priority by the sending server
if header :value "le" :comparator "i;ascii-numeric"
    "X-Priority" "2" {
    addflag "\\Flagged";
}

# File low-priority messages (4 or 5) into a "Low Priority" folder
if header :value "ge" :comparator "i;ascii-numeric"
    "X-Priority" "4" {
    fileinto "Low Priority";
    stop;
}

What this does: The X-Priority header uses numbers where 1 is most important and 5 is least. The :value "le" operator means "less than or equal to," so this catches priority 1 and 2 messages and flags them. Priority 4 and 5 messages get moved out of the inbox.

Important notes

Raw scripts replace visual filters. When you save a raw Sieve script, it replaces any filters you created with the visual builder for that mailbox. You cannot mix and match. Your visual filters are still saved in the database — they are just inactive while the raw script is active. To switch back to visual filters, click Reset to default at the top of the Sieve tab (see below).

The server validates before activating. When you click Save and activate, the server checks your script for syntax errors. If there is a problem, it will show you the error and refuse to activate the script. Your previous script (or visual filters) remain in place until you fix the issue.

The require statement is mandatory. Every extension you use must be listed in a require statement at the top of your script. If you use fileinto and vacation but forget to require them, the server will reject your script. When in doubt, include everything you might need.

Spam is filtered before your script runs. TrekMail's spam filter processes messages at the server level before Sieve scripts execute. Your script only sees messages that passed the spam check. You do not need to write spam-filtering rules in Sieve.

Switching back to visual filters

If you want to stop using a raw script and go back to the visual filter builder:

1. Open the Sieve tab for the mailbox.
2. Click Reset to default in the top-right corner of the editor.
3. Confirm the action when prompted.

This discards your custom script and restores the auto-generated script from your visual filters. Your visual filters (created on the Filters tab) are preserved in the database while a raw script is active — resetting simply re-activates them.

You can also switch back by saving any change on the Filters or Auto-Reply tabs. This will overwrite the raw script with the auto-generated one.

Common mistakes and how to fix them

Forgot the require statement. Every extension must be declared. If you see an error like "unknown command fileinto," add require ["fileinto"]; at the top.

Missing semicolons. Every command in Sieve ends with a semicolon. If the validator complains about unexpected tokens, check for missing semicolons, especially after stop, discard, and fileinto commands.

Strings must be quoted. Folder names, addresses, and comparison values need to be in double quotes. fileinto Newsletters; will fail. fileinto "Newsletters"; is correct.

Backslash in flags. IMAP flags like \Flagged and \Seen require a double backslash in Sieve: "\\Flagged" and "\\Seen". A single backslash is an escape character and will cause errors.

Folder does not exist. If you use fileinto with a folder name that does not exist, the behavior depends on server configuration. TrekMail will auto-create the folder in most cases, but it is good practice to create the folder in your email client first.

Script too large. There is a practical limit on script size. If your script grows beyond a few hundred lines, consider whether some of those rules could be handled by the visual filter builder instead. Not everything needs to live in one script.