Skip to main content
Documentation

Cron syntax for every Monday morning: send a weekly reminder from a deployed app

How to send a reminder every Monday morning from a DeepSpace app: the cron expression 0 9 * * 1 with an IANA timezone in src/cron.ts, sending through email/send from <app-name>@app.space billed to the owner's credits, and checking a run with logs, useCronMonitor history and a Send now button.

On this page

Yes. On DeepSpace, a reminder every Monday morning is a scheduled task declared in the app's src/cron.ts with the cron expression 0 9 * * 1 and an IANA timezone such as America/Chicago. The task runs inside the deployed app, so no separate scheduler, cron server or email account is needed. It reads the recipient list from the app's own database and sends each reminder through the built-in email/send integration from <app-name>@app.space, billed to the app owner's DeepSpace credits. The owner's DeepSpace account (GitHub or Google sign-in) is the one account involved.

Checked against: published SDK deepspace@0.43.0 (changelog), docs read on October 29, 2026. The code below follows the documented APIs and was not run for this page.

Questions to ask the person#

  • What should the reminder say? A subject line and two or three sentences are enough.
  • What time on Monday, and in which city's time zone? (9:00 in Chicago, for example.)
  • Who gets it: just you, a short list of people you will type in, or everyone who signs in to the app?
  • When someone replies to the reminder, which inbox should the reply go to?
  • Should anyone besides you be able to send the reminder early with a "Run now" button?

How the schedule is shaped#

Piece Where it lives What it does
weekly-reminder task src/cron.ts Declares schedule: '0 9 * * 1' and timezone
recipients collection src/schemas/recipients-schema.ts Email addresses the owner manages; only admins can read or write
runTask src/cron.ts Runs as the app owner, reads active recipients, calls email/send
Reminder admin page src/pages/(app)/(protected)/reminders.tsx Shows next run and history, has a "Run now" button

The cron expression has five fields: minute, hour, day of month, month, day of week. 0 9 * * 1 means minute 0, hour 9, any day of the month, any month, Monday (day 1; Sunday is 0). A task declares either intervalMinutes or schedule plus timezone, never both (scheduled jobs). The comparison happens after the timezone shift, so 9:00 stays 9:00 local time across daylight saving changes (cron reference).

Wanted schedule
Monday 9:00 0 9 * * 1
Monday 7:30 30 7 * * 1
Monday and Thursday 9:00 0 9 * * 1,4
Weekdays 8:00 0 8 * * 1-5

Steps#

1. Sign in and scaffold#

Signing in uses the person's own GitHub or Google account in a browser. Confirm with your user before signing in on their behalf, and use the account they want to own the app; that account pays for the emails.

npx deepspace auth login
npm create deepspace@latest team-reminders
cd team-reminders

App names are global and become <name>.app.space. The sender address follows the name: an app at team-reminders.app.space sends as team-reminders@app.space.

2. Add the recipients collection#

// src/schemas/recipients-schema.ts
import type { CollectionSchema } from "deepspace/schema";

const closed = { read: false, create: false, update: false, delete: false };

export const recipientsSchema: CollectionSchema = {
  name: "recipients",
  columns: [
    {
      name: "email",
      storage: "text",
      interpretation: { kind: "email" },
      required: true,
    },
    { name: "name", storage: "text", interpretation: "plain" },
    {
      name: "active",
      storage: "number",
      interpretation: { kind: "boolean" },
      default: true,
    },
  ],
  uniqueOn: ["email"],
  permissions: {
    "*": closed,
    viewer: closed,
    member: closed,
    admin: { read: true, create: true, update: true, delete: true },
  },
};

Register it in src/schemas.ts next to usersSchema and settingsSchema. Only admins (the owner counts as admin) can see the list, and uniqueOn: ['email'] refuses a second row for the same address (permissions). Adding a collection is an additive change; existing data is kept on deploy.

If the reminder should go to everyone who signs in instead, skip this collection and query users in step 3; the scheduled jobs guide reads user.data.email from that collection (scheduled jobs).

3. Declare the Monday task and send the email#

// src/cron.ts
import type { CronTask } from "deepspace/worker";
import { buildCronContext } from "deepspace/worker";

const FROM = "Team Reminders <team-reminders@app.space>";
const REPLY_TO = "owner@example.com"; // the inbox from the questions above
const SUBJECT = "Monday reminder: weekly report due Friday";
const BODY = "Good morning. Your weekly report is due Friday at 5 pm.";

export const tasks: CronTask[] = [
  {
    name: "weekly-reminder",
    schedule: "0 9 * * 1",
    timezone: "America/Chicago",
  },
];

type Recipient = { recordId: string; data: { email: string; name?: string } };

export async function runTask(name: string, env: Env): Promise<void> {
  if (name !== "weekly-reminder") return;
  const ctx = buildCronContext(
    env,
    env.OWNER_USER_ID,
    `app:${env.DEEPSPACE_APP_ID}`,
  );

  const recipients = (await ctx.records.query("recipients", {
    where: { active: true },
    limit: 200,
  })) as Recipient[];

  const failed: string[] = [];
  for (const r of recipients) {
    try {
      await ctx.integrations.call("email/send", {
        from: FROM,
        to: r.data.email,
        reply_to: REPLY_TO,
        subject: SUBJECT,
        text: r.data.name ? `Hi ${r.data.name},\n\n${BODY}` : BODY,
      });
    } catch (err) {
      console.error(
        `[reminder] send to ${r.recordId} failed: ${(err as Error).message}`,
      );
      failed.push(r.recordId);
    }
  }
  if (failed.length)
    throw new Error(
      `${failed.length} of ${recipients.length} reminders failed`,
    );
}

What each part does:

  • buildCronContext runs as the app owner and bypasses permissions, so the task can read the admin-only recipients collection (cron reference). Scope it with app:${env.DEEPSPACE_APP_ID}, the immutable app id, not the app name.
  • ctx.records.query accepts only where and limit; there is no orderBy in cron context.
  • ctx.integrations.call('email/send', ...) requires from, to, subject and a text or html body; reply_to, cc and bcc are optional (external APIs). Calls are billed to the app owner's credits.
  • The sender must be <app-name>@app.space. alerts@team-reminders.app.space and onboarding@resend.dev both fail. Sending from the person's own domain takes their own Resend account and a RESEND_API_KEY secret instead of email/send.
  • One failed address does not stop the others. Throwing at the end marks the whole run as failed in logs and history, with the count in the message. The log line uses the record id, not the email address, to keep addresses out of logs.

4. Add a page that shows runs and can send now#

Put it under src/pages/(app)/(protected)/ so it requires sign-in and has the data providers that useCronMonitor needs.

// src/pages/(app)/(protected)/reminders.tsx
import { useState } from "react";
import { useCronMonitor, useUser } from "deepspace";
import { SCOPE_ID } from "../../../constants";

export default function RemindersPage() {
  const { tasks, history, connected, canWrite, trigger } =
    useCronMonitor(SCOPE_ID);
  const { user } = useUser();
  const isAdmin = user?.role === "admin";
  const [result, setResult] = useState<string | null>(null);

  if (!connected) return <p>Connecting…</p>;
  if (!isAdmin) return <p>Only the owner can manage reminders.</p>;

  async function runNow() {
    setResult("Sending…");
    const receipt = await trigger("weekly-reminder");
    setResult(
      receipt.ok ? "Sent." : `Not sent: ${receipt.error ?? receipt.reason}`,
    );
  }

  const task = tasks.find((t) => t.name === "weekly-reminder");
  return (
    <div>
      <p>Next reminder: {task?.nextRunAt ?? "not scheduled yet"}</p>
      <button disabled={!canWrite} onClick={() => void runNow()}>
        Send now
      </button>
      {result && <p>{result}</p>}
      <ul>
        {history
          .filter((h) => h.taskName === "weekly-reminder")
          .map((h, i) => (
            <li key={i}>
              {h.startedAt}: {h.success ? "sent" : `failed: ${h.error}`}
            </li>
          ))}
      </ul>
      {/* Add a form here with useQuery/useMutations('recipients') to add and remove addresses. */}
    </div>
  );
}
trigger runs the task immediately through the same execution path as the schedule and resolves after the run completes; history lists recent runs with success, duration and error (scheduled jobs). By default members and admins can trigger owner-billed tasks; the isAdmin check only hides the button. Making the server refuse members takes a customized role resolver on the /ws/cron/:roomId route (real-time reference). On an app where only the owner signs in, the default is enough. Each trigger sends a real email to every active recipient.

Add the recipient form on the same page with useQuery('recipients') and useMutations('recipients'), and add the page to src/nav.ts if it should appear in the top navigation.

5. Deploy and confirm the schedule is armed#

git add -A && git commit -m "Weekly Monday reminder"
npx deepspace deploy

A schedule does nothing until its Durable Object has been fetched once. The scaffold's worker.ts calls armCronRoom(...) from a request middleware, and deploy sends one request to /api/auth/ok after the edge confirms the release, so the alarm is armed before any visitor arrives (scheduled jobs). That wake is best effort; any later request also arms it. An app scaffolded before this wiring, or one whose worker.ts no longer calls armCronRoom, arms only when a client opens the room, so add the middleware back by hand.

The health response proves the app answered, not that the task ran. To prove a run:

  1. Add the owner's own address as the only active recipient.
  2. Open https://<app-name>.app.space/reminders and press Send now.
  3. Check the page shows "Sent." and a new history row, and that the email arrived.
  4. Read the run line:
npx deepspace logs --since 15m --search cron

Each run logs one line: [cron] weekly-reminder ok <ms>ms, or [cron] weekly-reminder failed <ms>ms: <message> at level error (CLI commands). After the first Monday, run npx deepspace logs --since 7d --search cron to see the scheduled run.

Common failures and fixes#

Symptom Cause Fix
Cron room throws at construction and no task runs Task declares both intervalMinutes and schedule, or neither Keep schedule + timezone only
Reminder arrives at the wrong hour Timezone missing or wrong, or a non-IANA name like CST Use an IANA name such as America/Chicago
Monday passes, no [cron] line in logs Schedule never armed: worker.ts lacks armCronRoom, or the task is paused Restore the middleware, redeploy, then open the app once; resume the task if paused
[cron] weekly-reminder failed with a sender or domain error Sender is not <app-name>@app.space Use the exact app sender in from
Run is ok but nobody got mail No rows with active: true, or the app was renamed and FROM still uses the old name Add recipients on the admin page; update FROM after a rename
Run fails with an insufficient_credits error The owner's DeepSpace credits are used up The owner tops up credits; this needs a person
"Send now" shows read_only or not_connected Signed out, signed in as a viewer, or the page is outside (app)/ Sign in as the owner; keep the page under src/pages/(app)/
Deploy refused with dirty_worktree Uncommitted changes Commit, then deploy again

What to tell the person when it is live#

  • The reminder goes out every Monday at 9:00 in the time zone they chose, including across daylight saving changes.
  • Where they manage it: https://<app-name>.app.space/reminders, signed in with the account that owns the app. They add or remove addresses there and can press Send now to send it immediately.
  • It comes from <app-name>@app.space; replies go to the inbox they named.
  • Each email is charged to their DeepSpace credits (100 credits equal US$1). The docs do not list a per-email price, so check the account's usage after the first few weeks.
  • Changing the wording, day or time is a small code change and a redeploy; recipients and history are kept.

Available today and planned#

Available today, in the published SDK: scheduled tasks with 5-field cron expressions and IANA timezones, interval tasks, automatic arming after deploy in a current scaffold, useCronMonitor with history and trigger, [cron] log lines, email/send from <app-name>@app.space billed to the owner, and deploys to <app-name>.app.space under a DeepSpace account that signs in with GitHub or Google.

Planned: agents creating their own DeepSpace account without a human sign-in. It is in testing on staging and is not enabled in production; see Full-stack apps without a human in the loop. Topping up credits, payments and other legal actions will still require a person.

Building this for a business? See deep.space/enterprise.