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.

An active Agency plan is required to activate a raw script. Other plans can save a draft in the editor, but it will not run.

What is Sieve?

Sieve is a small scripting language for email filtering. Think of it as instructions that run whenever a new message arrives. A rule can check the sender, subject, size, or headers, then move the message to a folder, forward it, flag it, reject it, or send an 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 need logic that cannot be expressed with the visual builder's conditions and actions.
• You are managing templates that you copy across many mailboxes.

Where to find it

1. Open the TrekMail dashboard and go to Mailboxes.
2. Choose Manage next to the mailbox you want to configure.
3. Select the Sieve tab.
4. You will see a code editor. On an eligible Agency account it starts with the script generated from your managed filters, if you have any. 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, declare it at the top of your script with a require statement. The server checks the script before activation and rejects unsupported or security-sensitive extensions.

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 stay saved but are inactive while the raw script is active. To switch back to visual filters, click Reset to default at the top of the Sieve tab.

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 while a raw script is active, resetting simply re-activates them.

Saving a change on the Filters tab also returns the mailbox to the managed script. The Auto-reply tab does not overwrite a raw script; reset to managed mode first, then set the auto-reply.

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. Create the folder in your email client before routing mail to it. A raw script does not automatically create a missing folder unless the script and server support that behavior.

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.