gmail_search_syntax

Parser for Gmail's search syntax. Converts Gmail search queries into an Abstract Syntax Tree.

Based on the official Gmail search operators documentation:
https://support.google.com/mail/answer/7190

[!TIP] This gem was created for Cora, your personal e-mail assistant. Send them some love for allowing me to share it.

Installation

gem 'gmail_search_syntax'

Usage

require 'gmail_search_syntax'

ast = GmailSearchSyntax.parse!("from:boss subject:meeting")
# => #<And #<Operator from: "boss"> AND #<Operator subject: "meeting">>

Afterwards you can do all sorts of interesting things with this, for example - transform your AST nodes into Elastic or SQL queries, or execute them bottom-op just from arrays in memory.

Examples

# Simple operator
GmailSearchSyntax.parse!("from:[email protected]")
# => #<Operator from: "[email protected]">

# Logical OR
GmailSearchSyntax.parse!("from:amy OR from:bob")
# => #<Or #<Operator from: "amy"> OR #<Operator from: "bob">>

# Negation
GmailSearchSyntax.parse!("dinner -movie")
# => #<And #<StringToken "dinner"> AND #<Not #<StringToken "movie">>>

# Proximity search
GmailSearchSyntax.parse!("holiday AROUND 10 vacation")
# => #<Around #<StringToken "holiday"> AROUND 10 #<StringToken "vacation">>

# Complex query with OR inside operator values
GmailSearchSyntax.parse!("from:{alice@ bob@} subject:urgent")
# => #<And #<Operator from: #<Or ...>> AND #<Operator subject: "urgent">>

# Empty queries raise an error
GmailSearchSyntax.parse!("")
# => raises GmailSearchSyntax::EmptyQueryError

Supported Operators

Email routing: from:, to:, cc:, bcc:, deliveredto:
Metadata: subject:, label:, category:, list:
Dates: after:, before:, older:, newer:, older_than:, newer_than:
Attachments: has:, filename:
Status: is:, in:
Size: size:, larger:, smaller:

Features

  • Handles operator precedence (negation, AROUND, implicit AND, explicit AND, OR)
  • Supports grouping with parentheses and braces
  • Recognizes emails, dates, quoted strings, and numbers
  • Minimal AST structure

There is also a converter from the operators to SQL queries against an embedded SQLite database. This is meant more as an example than a fully-featured store, but it shows what's possible.

Converting to SQL

The gem includes a SQLite visitor and a Postgres visitor which converts the Gmail queries into corresponding SQL. See SCHEMA.md for more information.

require 'gmail_search_syntax'

# A complex Gmail query with multiple operators
query = '(from:manager OR from:boss) subject:"quarterly review" has:attachment -label:archived after:2024/01/01 larger:5M'

ast = GmailSearchSyntax.parse!(query)
visitor = GmailSearchSyntax::SQLiteVisitor.new(current_user_email: "[email protected]")
visitor.visit(ast)

sql, params = visitor.to_query.to_sql

Testing

bundle exec rake test

License

MIT

Gmail is a trademark of Google LLC.