EmailSpaceEmailSpace
HomeDocsGet started

Automations

Automations send lifecycle and reminder email from read-only data sources using templates you publish to AWS SES. Typical uses: birthday wishes, onboarding follow-ups, and re-engagement when users have been inactive for N days.

Requires AWS SES. Connect and verify AWS SES under Project → Email provider before running automations. Templates must be published to SES. See the AWS SES guide for setup.

Automations are separate from Campaigns, which handle one-off marketing broadcasts to filtered audiences from the same data connections.

Supported data sources:

  • MongoDB — live database connection (read-only)
  • Excel / CSV — uploaded spreadsheet (.xlsx, .xls, .csv)

Connect MongoDB (read-only)

  1. In your MongoDB cluster, create a user with read access only on the target database (no readWrite, no dbAdmin).
  2. In the project Automations tab, open Data connections → Add connection → MongoDB.
  3. Paste the connection URI and database name. EmailSpace tests the connection, encrypts the URI at rest, and never returns the secret to the browser after save.

Example user (adjust roles for your deployment):

db.createUser({
  user: "emailspace_readonly",
  pwd: "…",
  roles: [{ role: "read", db: "myapp" }],
});

Upload Excel / CSV

  1. Open Data connections → Add connection → Excel / CSV.
  2. Choose a file (max 10 MB by default), set a display name, and confirm the header row (default: row 1).
  3. EmailSpace parses sheets, infers column types, and stores rows for automation audiences.
  4. Use Re-upload on the connection edit page to refresh data from a new file.

Each sheet is treated as a collection in the automation builder. Column headers become field names for mapping and filters.

Browse data

After connecting, open Browse on a connection to list collections/sheets and preview rows. No insert, update, or delete operations are exposed in the API.

Create an automation

  1. Choose a connection and collection (or sheet).
  2. Set the email field (and optional name field for {{firstName}}).
  3. Pick a published template and map template variables to document/row fields.
  4. Define the audience (see Audience filters below).
  5. Set a schedule: every N days or a cron expression (requires the scheduled-runs plan permission), or choose manual runs only.
  6. Use Preview audience to count matching rows/documents before enabling.

Use New automation → Manual builder or AI builder. Both support the same audience modes.

Audience filters

ModeDescription
NormalVisual query builder on a single collection/sheet: conditions with AND / OR / NOT groups, field operators (equals, null, in list, contains, regex, date helpers, etc.).
AdvancedRaw filter JSON. MongoDB connections support find filters and aggregation pipelines. Excel connections support find mode only (row filters). Operators like $where are blocked.

Phase 2 (planned): join multiple collections in Advanced mode (MongoDB only).

Normal mode operators

equals, not equals, greater/less than, in / not in, is null / not null, is empty / not empty, contains, regex, older/newer than N days, before/after date, and nested NOT groups.

AI audience builder (Advanced)

Describe your audience in plain language. AI generates a filter using the connection catalog (collections/sheets and column fields). For Excel, only find-mode row filters are generated.

Example: birthday today

Normal: field birthday, operator birthday today.

Example: members inactive for 2 days

Normal: field lastPostAt, operator older than (days), value 2. You can combine rules, e.g. status equals active AND lastPostAt older than 2 days.

Advanced:

{
  "mode": "find",
  "filter": {
    "lastPostAt": { "$lt": "{{computed:nowMinusDays:2}}" }
  }
}

The server resolves {{computed:nowMinusDays:N}} at run time.

Runs and sending

  • Run now enqueues a job immediately (project owner only).
  • Scheduled automations are picked up every minute via Redis/BullMQ.
  • Each matching row/document becomes one send job through your connected AWS SES account.
  • Connect AWS SES under Project → Email provider before running automations.
  • Sends are rate-limited (default ~10/second per queue) and logged in analytics with source: automation.

Limits and security

ControlDefault / notes
AUTOMATION_QUERY_MAX_DOCS10,000 rows/documents scanned per run
AUTOMATION_MONGO_MAX_TIME_MS15s query timeout (MongoDB)
DATA_UPLOAD_MAX_BYTES10 MB max spreadsheet upload
DATA_UPLOAD_DIRServer path for uploaded files (Docker volume in Compose)
Plan maxRecipientsPerRunCaps enqueued sends per run
Recipient dedupSame email once per run (hash)
CredentialsAES-256-GCM, same key as ESP credentials

Infrastructure

Docker Compose includes Redis for BullMQ and a data_uploads volume for spreadsheet files. Set REDIS_URL on the backend (e.g. redis://redis:6379).

Apply migrations backend/migrations/013_automations.sql and 014_excel_connections.sql in production if not using TypeORM synchronize.

Coming later

  • Multi-collection joins in Advanced audience mode (MongoDB).
  • MySQL, PostgreSQL, REST API, Shopify, HubSpot, and other connectors.

Previous

Node.js SDK

Next

Campaigns