Actions

Convex actions — for side effects, third-party API calls, and anything that touches the outside world.

Actions can call third-party APIs, use process.env, run for up to 10 minutes, and orchestrate other Convex functions. They’re not transactional — for atomicity, do data writes inside mutations called from the action.

Anatomy

convex/notifications.ts

import { action } from "./_generated/server";
import { v } from "convex/values";
import { api } from "./_generated/api";

export const sendWelcomeEmail = action({
  args: { userId: v.id("users") },
  handler: async (ctx, { userId }) => {
    const user = await ctx.runQuery(api.users.get, { id: userId });
    if (!user) return;

    await fetch("https://api.resend.com/emails", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.RESEND_API_KEY}`,
        "Content-Type":  "application/json",
      },
      body: JSON.stringify({
        from: "[e-mail]",
        to: user.email,
        subject: "Welcome",
        html: `<p>Hi ${user.name}, welcome.</p>`,
      }),
    });

    await ctx.runMutation(api.users.markWelcomed, { id: userId });
  },
});

ctx.run* helpers

Inside an action, call other Convex functions:

const user   = await ctx.runQuery(api.users.get, { id });
const result = await ctx.runMutation(api.users.update, { id, ... });
const data   = await ctx.runAction(api.other.someAction, { ... });

On the client

import { useAction } from "convex/react";
const send = useAction(api.notifications.sendWelcomeEmail);
await send({ userId });

When to pick action vs mutation

Need	Function type
Write to the DB only	Mutation
Read from the DB only	Query
Call a third-party API	Action
Use process.env	Action
Long-running work (>10s)	Action

Limits

• 10-minute runtime per invocation.
• Not transactional: a failure mid-action leaves the world in whatever partial state was reached.
• No reactive subscriptions — clients call actions, but actions don’t push back.

Tips

Wrap third-party calls in try/catch. External APIs fail; handle the failure gracefully.

For idempotency, store a key in the DB. Before calling Stripe / Resend / etc., check whether you’ve already done this work.

Related

Mutations

For DB writes called from actions.

Queries

For DB reads called from actions.

Background jobs

Long-running patterns.