# 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.

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](https://deep.space/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](https://docs.deep.space/guides/scheduled-jobs)). The comparison happens after the timezone shift, so 9:00 stays 9:00 local time across daylight saving changes ([cron reference](https://docs.deep.space/sdk-reference/worker/cron)).

| 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.

```bash
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

```ts
// 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](https://docs.deep.space/concepts/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](https://docs.deep.space/guides/scheduled-jobs)).

### 3. Declare the Monday task and send the email

```ts
// 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](https://docs.deep.space/sdk-reference/worker/cron)). 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](https://docs.deep.space/guides/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.

```tsx
// 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](https://docs.deep.space/guides/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](https://docs.deep.space/sdk-reference/client/realtime)). 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

```bash
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](https://docs.deep.space/guides/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:

```bash
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](https://docs.deep.space/cli-reference/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](/agents/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](https://deep.space/enterprise).
