Events and triggers

Mashlets can be run in four ways:

Mode	When the mashlet runs
Manual	The user runs it from the script editor, or picks it from a file’s action menu.
Scheduled	A cron (or daily/weekly/monthly) schedule fires the mashlet against a configurable list of files. The schedule’s file_source.
Event	The mashlet is bound to a system event (file uploaded, mail received, user signed in, etc.) and runs each time that event fires.
Webhook	An HTTP request to a per-hook URL fires the mashlet, with the request body and headers available inside the script.

Manual and scheduled triggers are configured in Foldr Settings > Automation, alongside the mashlet itself. Event and webhook triggers are configured in the same screen by attaching the mashlet to an event or hook.

Scheduled triggers and file_source

A scheduled mashlet runs against a list of files resolved at run time from its file_source configuration. Four modes are available:

type	Resolves to
folder	Every file in a folder on a given share.
glob	Files in a folder whose names match a glob pattern.
field_filter	Files (cross-share) whose custom field values match a filter set.
explicit	A hand-picked list of (share_id, path) entries.

The resolver enforces a soft cap of 1000 files per run to prevent runaway expansion; if a file_source resolves to more, the mashlet’s mash.event.files_truncated flag is set so the script can react. If you genuinely need to process more than 1000 files in one go, split into multiple scheduled mashlets or batch via field filters.

Event triggers

When a mashlet is bound to an event, Foldr fires it each time that event occurs. The event’s payload (the file, user, mail, etc.) is available inside the script through mash.event.

File events

Event	When it fires
Uploaded	A file is uploaded through the Foldr web app, desktop app, or the API.
Downloaded	A file is downloaded from the Foldr web app or opened via a native Foldr app.
Indexed	The Foldr search index successfully indexes a file. If Captur is in play, any extracted data is available alongside the file.
Crawled	The crawler visits a file (whether or not it ends up indexed). Useful for housekeeping that should happen once per crawl pass regardless of indexing outcome.
Moved	A file is moved to a new location.
Copied	A file is copied.
Deleted	A file is deleted.
Shared	A file is shared (internally with another user, or externally via a public or secure link).
Fields Changed	A file’s custom field data is changed by a user in one of the Foldr apps.

Event mashlets can be filtered by path prefix and file extension when configured, so you can scope a mashlet to a specific share or file type without doing the filtering in the script body.

User events

Event	When it fires
Signed In	A user successfully signs in to Foldr.

Mail events

Event	When it fires
Mail Received	An email is received by a configured Inbox share. Fires once per email regardless of attachment count, with all attachments aggregated into the event payload. (See also: Inbox: receiving email to shared folders for the SMTP setup.)

A note on attachment-level vs email-level events. When a user emails files into an Inbox share, each attachment also surfaces as a separate Uploaded event. That means an event mashlet bound to Uploaded can react per attachment (one run per file), while a mashlet bound to Mail Received runs once per email with the whole batch of attachments. Pick the mode that matches what you want to do. Most “process the inbound message and its files together” automations want Mail Received.

Webhook hooks

A mashlet can be exposed as an HTTP endpoint by binding it to a webhook hook. When the hook URL is hit, the mashlet runs with the request available as mash.request (body, query, headers, method). Each hook gets its own random URL when created. The URL is stable per hook and acts as the shared secret, so don’t paste it anywhere public.

Both GET and POST are supported. The mashlet’s return value is sent back as the HTTP response body. Use this when you need an external service to trigger Foldr behaviour (e.g. a Zapier action that drops a row of data into Foldr, or a build system that asks Foldr to run a check).

The event object

When a mashlet is run as part of an event or webhook, the triggering context is available through mash.event:

Natural

# The file (if any) attached to the event.
# Null for user events; null for mail events (use mash.event.mail instead).
printline mash.event.file

# The user (if any) attached to the event.
# Some file events may have no user (e.g. Crawled, indexed by the system).
printline mash.event.user

# For Mail Received events: the email itself
# (subject, from, to, attachments, body).
printline mash.event.mail

Standard

printline(mash.event.file)
printline(mash.event.user)
printline(mash.event.mail)

For scheduled mashlets, mash.event.file cycles through each resolved file in turn, and mash.event.files_truncated is true if the resolver hit the 1000-file soft cap.

Notes

• File events often have a user attached (the user who triggered them). Some. Like Crawled. May not.
• On Indexed events, custom field values populated by Captur are available on the file via mash.event.file.fields.