Send emails with Convex

Documentation Index

Fetch the complete documentation index at: https://docs.autosend.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Install with your AI assistant

Help me install the AutoSend component.

Package: @autosend/convex
Install: npm install @autosend/convex

Documentation:
- https://www.convex.dev/components/autosend/convex/convex.md
- https://www.convex.dev/components/autosend/convex/llms.txt

Please:
1. Retrieve the install command and documentation
2. Generate an exact setup checklist for this component
3. List any required environment variables
4. Provide verification steps

​

What you get

• Queue-first sending. sendEmail and sendBulk enqueue jobs and automatically trigger queue processing.
• Idempotency. Duplicate requests resolve to the same emailId, so retried mutations never double-send.
• Retries with backoff. Network errors, 429, and 5xx responses are retried on a configurable schedule.
• Lifecycle tracking. Every email moves through queued, sending, retrying, sent, failed, or canceled.
• Webhook ingestion. HMAC SHA-256 signature verification, timestamp skew protection, and per-delivery dedupe out of the box.
• Templates, CC/BCC, attachments, and unsubscribe groups are all supported.
• Test sandbox. Optional sandboxTo rewrites recipients while you are still wiring things up.

​

Prerequisites

• An AutoSend account with an API key
• A verified sending domain
• A Convex project (Convex CLI installed and npx convex dev runnable)
• Node.js 18+ installed locally

​

Install

npm install @autosend/convex convex

​

Setup

import { defineApp } from "convex/server";
import autosend from "@autosend/convex/convex.config.js";

const app = defineApp();
app.use(autosend, { name: "autosend" });
export default app;

import { AutoSend } from "@autosend/convex";
import { components } from "./_generated/api";

export const autosend = new AutoSend(components.autosend);

npx convex env set AUTOSEND_API_KEY <your-api-key>
npx convex env set AUTOSEND_WEBHOOK_SECRET <your-webhook-secret>

import { mutation } from "./_generated/server";
import { autosend } from "./email";

export const configureAutosend = mutation({
  args: {},
  handler: async (ctx) => {
    await autosend.setConfig(ctx, {
      config: {
        autosendApiKey: process.env.AUTOSEND_API_KEY!,
        webhookSecret: process.env.AUTOSEND_WEBHOOK_SECRET!,
        defaultFrom: "[email protected]",
        testMode: true,
        sandboxTo: ["[email protected]"],
      },
    });
  },
});

import { httpRouter } from "convex/server";
import { registerRoutes } from "@autosend/convex";
import { components } from "./_generated/api";

const http = httpRouter();
registerRoutes(http, components.autosend);
export default http;

https://YOUR-DEPLOYMENT.convex.site/webhooks/autosend

​

Send your first email

import { mutation } from './_generated/server';
import { v } from 'convex/values';
import { autosend } from './email';

export const sendWelcome = mutation({
	args: { email: v.string(), name: v.string() },
	handler: async (ctx, { email, name }) => {
		const { emailId } = await autosend.sendEmail(ctx, {
			to: [email],
			toName: name,
			subject: 'Welcome to Acme',
			html: `<h1>Hi ${name}</h1><p>Thanks for signing up.</p>`,
		});

		return emailId;
	},
});

​

Sending variants

await autosend.sendEmail(ctx, {
  to: ["[email protected]"],
  templateId: "tmpl_welcome",
  dynamicData: {
    firstName: "Jane",
    loginUrl: "https://app.example.com/login",
  },
});

await autosend.sendEmail(ctx, {
  to: ["[email protected]"],
  cc: [{ email: "[email protected]", name: "Support Team" }],
  bcc: [{ email: "[email protected]" }],
  replyTo: "[email protected]",
  replyToName: "Acme Support",
  subject: "Your order",
  html: "<p>Thanks for your purchase.</p>",
});

await autosend.sendEmail(ctx, {
  to: ["[email protected]"],
  subject: "Your invoice",
  html: "<p>Invoice attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      fileUrl: "https://files.example.com/invoice.pdf",
      contentType: "application/pdf",
    },
    {
      filename: "summary.csv",
      content: "base64-encoded-content",
      contentType: "text/csv",
    },
  ],
});

await autosend.sendBulk(ctx, {
  recipients: ["[email protected]", "[email protected]"],
  subject: "Product update",
  html: "<p>We shipped new features this week.</p>",
});

await autosend.sendBulk(ctx, {
  recipients: ["[email protected]", "[email protected]"],
  recipientData: {
    "[email protected]": { name: "Alice", role: "admin" },
    "[email protected]": { name: "Bob", role: "member" },
  },
  subject: "Welcome, {{name}}",
  html: "<p>Hi {{name}}, you are now a {{role}}.</p>",
});

await autosend.sendEmail(ctx, {
  to: ["[email protected]"],
  subject: "Order #1234 confirmation",
  html: "<p>Thanks for your order.</p>",
  idempotencyKey: `order:1234:confirmation`,
});

​

Track status and events

import { query } from './_generated/server';
import { v } from 'convex/values';
import { autosend } from './email';

export const getEmailStatus = query({
	args: { emailId: v.string() },
	handler: async (ctx, { emailId }) => {
		const email = await autosend.status(ctx, { emailId });
		const events = await autosend.listEvents(ctx, { emailId, limit: 20 });
		return { email, events };
	},
});

// Batch status for multiple emails in one call
const statuses = await autosend.statusBatch(ctx, {
	emailIds: [id1, id2, id3],
});

// Cancel an email that has not been sent yet
const { canceled } = await autosend.cancelEmail(ctx, { emailId });

​

Email lifecycle

​

Configuration

const safeConfig = await autosend.getConfig(ctx);

​

Go live checklist

1. Verify your sending domain in the AutoSend dashboard (domain setup).
2. Deploy your Convex backend so the webhook route is reachable.
3. Add the webhook URL https://YOUR-DEPLOYMENT.convex.site/webhooks/autosend to your AutoSend project and copy the signing secret into AUTOSEND_WEBHOOK_SECRET.
4. Send a test email with testMode: true and confirm the status moves to sent and you see email.delivered in listEvents.
5. Update config with testMode: false and a real defaultFrom.

​

Troubleshooting

await autosend.processQueue(ctx, { batchSize: 25 });

​

Resources

• Component listing on Convex
• Source code on GitHub
• @autosend/convex on npm
• Live demo