README

This library allows you to define Gmail filters in PHP, and then generate XML that you can import into Gmail's filter settings

Inspired by https://github.com/antifuchs/gmail-britta.

Installation and Basic Usage

Step 1: Require the Library

composer require opdavies/gmail-filter-builder

Step 2: Create Your Filters File

Create a filters.php file that returns an array of Filter objects.

For example:

<?php

require_once __DIR__.'/vendor/autoload.php';

return [
    // Add your filters.
];

Step 3: Generate the XML

Run ./vendor/bin/generate-filters to generate the XML for the filters and export it into a file.

Options

--input-file - specify the name of the file containing the filters (defaults to filters.php).
--output-file - specify the name of the output file (defaults to filters.xml).

Step 4: Import the Filters

Available Methods

Conditions

Conditions that a message must satisfy for the filter to be applied:

has - can be used to check for various properties, such as attachments, stars or labels. Can also be used as an alternative to some of the following methods previously - e.g. from:john@example.com - and can be useful for more advanced queries.
hasNot - the opposite of the above.
from - if the message is from a certain name or email address.
to - if the message is to a certain name or email address.
subject - if the message has a certain subject.
hasAttachment - if the message has an attachment.
fromList - if the message is from a mailing list.
excludeChats - exclude chats from the results (false by default).

Actions

Actions you can apply to messages that match the conditions:

label - add a label to the message.
archive - archive the message (skip the inbox).
labelAndArchive - both add a label and archive the message.
spam - mark the message as spam.
neverSpam - never mark the message as spam.
trash - delete the message.
read - mark the message as read.
star - star the message.
forward - forward the message to another email address.
important - mark the message as important.
notImportant - mark the message as not important.
categorise - apply a smart label to the message.

Loading Filters from Partials

If you want to split your filters into different partials, return an array of filters within each one and add return Opdavies\GmailFilterBuilder\Service\Partials::load() to filters.php to load and combine them.

This defaults to a directory called filters, but you can specify an alternative directory name as an argument.

Loading Addresses from a Separate File

If you want to filter based on the to address and not include your addresses within the filters repository, you can include them from within a different file using Addresses::load():

$myAddresses = Addresses::load('my-addresses.php');

return [
    Filter::create()
        ->from('foo@example.com')
        ->to($myAddresses)
        ->trash(),
];

In this example, the addresses are returned as an array from ~/.gmail-filters/my-addresses.php and then used as a condition in the filter.

Filter Examples

// If an email is from a certain address, add a label.
Filter::create()
    ->from('john@example.com')
    ->label('Something');

References

Search operators you can use with Gmail

opdavies / gmail-filter-builder

Maintainers

Details