Mailscript Documentation

A comprehensive guide to the Starlark-powered content filtering language for msgs.global.

Introduction

Mailscript allows you to write advanced, sandboxed email routing and mutation policies using Starlark (a Python dialect). These scripts execute on the `go-emailservice-ads` edge nodes, granting you unparalleled control over email flow before messages even reach traditional mailboxes.

Basic Example

# Example: Block emails from a specific domain
from_addr = ctx["from"]
if from_addr.endswith("@spammer.com"):
    reject("Spam domain blocked by policy")

# Example: Quarantine emails containing PII
result = dlp_scan(ctx["body"])
if result["has_pii"]:
    mail.quarantine("Contains sensitive data")

Global Functions

reject(reason: str)
Immediately aborts processing and rejects the email at the SMTP transaction level with a 550 error containing the provided reason.
log(msg: str)
Writes a message to the server's internal logging system. Useful for debugging scripts.
b64encode(data: str) -> str
Returns the Base64 encoded string of the given data.
b64decode(data: str) -> str
Decodes a Base64 encoded string. Returns an error if the data is malformed.
http_get(url: str) -> str
Performs a synchronous HTTP GET request (5-second timeout) and returns the body. Useful for checking external threat intelligence feeds.
regex_match(pattern: str, text: str) -> bool
Returns True if the regular expression pattern matches the given text.
dlp_scan(text: str) -> dict
Scans the text using the platform's Data Loss Prevention (DLP) engine. Returns a dictionary containing flags like `has_pii`, `has_credit_card`, and `has_ssn`.
mime_extract(raw_email: str) -> list of dict
Parses a raw MIME string and returns a list of dictionaries representing the extracted parts, containing `content_type` and `body`.

The mail Object

The globally available `mail` object exposes methods to mutate the email or alter its final routing destination. These actions take precedence when the script finishes executing.

mail.add_header(key: str, value: str)
Appends a new header to the email before delivery.
mail.remove_header(key: str)
Removes a header from the email.
mail.replace_body(body: str)
Overwrites the text/plain body of the email.
mail.quarantine(reason: str)
Routes the message to the quarantine storage instead of the user's inbox.
mail.drop()
Silently discards the email. Returning a 250 OK to the sender, but deleting the message data.
mail.deliver()
Explicitly marks the email for guaranteed inbox delivery, bypassing later filters.
mail.redirect(to: str)
Changes the envelope recipient, routing the email to a different email address entirely.