Backend Functions

The ctx Object

Every backend function receives a ctx object and a params object. The ctx object provides access to all platform features:

ctx.tables — Database Operations

All 13 methods available on ctx.tables. These respect the table's access rules based on the calling user.

ctx.service.tables and ctx.service.files have the same methods as their regular counterparts but bypass all access rules. Use these for admin operations that need unrestricted access.

// Example: admin function to get all orders regardless of access rules
const allOrders = await ctx.service.tables.getRows('Orders');
return allOrders;

ctx.fetch — External APIs

Make HTTPS requests to external services. Supports environment variable placeholders using {{VAR_NAME}} syntax.

// Call an external API with an env var for the API key
const result = await ctx.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer {{API_KEY}}' },
  body: JSON.stringify({ query: params.query }),
  timeout: 10000,
});

// result = { status: 200, data: { ... } }

ctx.files — File Operations

ctx.env — Environment Variables

const value = await ctx.env.get('STRIPE_SECRET_KEY');

Environment variables are encrypted at rest and only decrypted when your function executes. Set them in your app's Config tab. See Environment Variables for more details.

ctx.email — Sending Email

Send transactional email under the project's verified sender identity. Runs as the project/owner, so it isn't gated by the project's member-facing email access rules.

await ctx.email.send({
  to: 'customer@example.com',       // string or array of strings
  subject: 'Your order shipped',
  html: '<p>Order #123 is on its way.</p>',
  text: 'Order #123 is on its way.', // optional
  replyTo: 'support@yourapp.com',    // optional
  template: 'order-shipped',         // optional — use a saved email template instead of html/text
  data: { orderId: '123' },          // optional — template variables
});

Capped at 50 recipients per call and subject to your account's monthly email quota. See Email Templates.

Sending from your own mailbox

For outreach, newsletters or anything at volume, send through your own SMTP mailbox instead. Add it under Automations → Email, then send by name — no monthly platform quota applies, and mail leaves your domain and your sending reputation rather than the shared platform sender.

// which mailboxes are available (no credentials are ever returned)
const { scope, accounts } = await ctx.email.accounts();
// scope: 'member' = the signed-in member's own mailboxes (empty = THEY have none)
//        'account' = your account's mailboxes (no member signed in)
// accounts: [{ id, name, fromAddress, verified, isDefault }]
// Need your account's mailboxes while a member is signed in?
//   const { accounts } = await ctx.service.email.accounts();

await ctx.email.sendVia('outreach', {
  to: 'prospect@example.com',
  subject: 'Quick question',
  html: '<p>Hello…</p>',
  unsubscribeUrl: 'https://yoursite.com/unsubscribe?e=…', // always set for marketing
});
// → { success, messageId, skipped?, fromName, fromNameOverridden }
//   skipped = suppressed recipients

await ctx.email.sendVia(null, { to, subject, html }); // null = default mailbox

// One mailbox, several identities — set the display name per send.
// The ADDRESS never changes (it is the verified, SPF/DKIM-aligned one).
await ctx.email.sendVia('outreach', {
  to, subject, html,
  fromName: "Ken's Hardware Team",   // recipients see this name
});

ctx.entitlements — Paid Access

The entitlement ledger backs the has_entitlement access rule. ctx.entitlements is the only way to write to it — grant access after a successful payment, then gate tables/files/functions/pages behind the same key.

Access Rules

Control who can execute your function. No rules configured = only the app owner can call it.

See Access Control for a complete guide on all rule types (including has_entitlement, function, and relationship).

Calling from Your App

In your published app's pages, import and call backend functions using the SDK:

// In your app's page code:
import { functions } from '../api/sdk';

const result = await functions.call('processOrder', {
  item: 'Widget',
  quantity: 3,
});

// result = { success: true, data: { orderId: '...' }, executionTime: 150 }

Functions are also reachable directly over HTTP (e.g., from an external webhook). The raw JSON request body is the params object — no wrapper:

POST /api/app-builder/{projectId}/functions/processOrder
Content-Type: application/json

{ "item": "Widget", "quantity": 3 }

// Response is the same shape: { success, data, executionTime }

The same access rules apply either way — an unauthenticated or under-permissioned external caller gets the same deny response a logged-out SDK call would.