Thanks for signing up.
`,
});
return emailId;
},
});
```
If you omit `from`, the component uses the `defaultFrom` you set in config. The returned `emailId` is the handle you use to query status and webhook events later.
## Sending variants
Reference an AutoSend email template by ID and pass merge fields via `dynamicData`.
```ts theme={null}
await autosend.sendEmail(ctx, {
to: ["jane@example.com"],
templateId: "tmpl_welcome",
dynamicData: {
firstName: "Jane",
loginUrl: "https://app.example.com/login",
},
});
```
When you use `templateId`, `subject` and `html` are optional. See template variables for the syntax supported in your template.
```ts theme={null}
await autosend.sendEmail(ctx, {
to: ["customer@example.com"],
cc: [{ email: "team@example.com", name: "Support Team" }],
bcc: [{ email: "archive@example.com" }],
replyTo: "support@example.com",
replyToName: "Acme Support",
subject: "Your order",
html: "Thanks for your purchase.
",
});
```
Attach files inline as base64 or by URL.
```ts theme={null}
await autosend.sendEmail(ctx, {
to: ["customer@example.com"],
subject: "Your invoice",
html: "Invoice attached.
",
attachments: [
{
filename: "invoice.pdf",
fileUrl: "https://files.example.com/invoice.pdf",
contentType: "application/pdf",
},
{
filename: "summary.csv",
content: "base64-encoded-content",
contentType: "text/csv",
},
],
});
```
Provide either `fileUrl` or `content`, never both.
Send the same payload to up to 100 recipients in one call.
```ts theme={null}
await autosend.sendBulk(ctx, {
recipients: ["alice@example.com", "bob@example.com"],
subject: "Product update",
html: "We shipped new features this week.
",
});
```
Each recipient is queued as a separate email, so retries and webhook events are tracked per recipient.
Pass `recipientData` keyed by email to interpolate `{{placeholders}}` into `subject`, `html`, and `text` per recipient.
```ts theme={null}
await autosend.sendBulk(ctx, {
recipients: ["alice@example.com", "bob@example.com"],
recipientData: {
"alice@example.com": { name: "Alice", role: "admin" },
"bob@example.com": { name: "Bob", role: "member" },
},
subject: "Welcome, {{name}}",
html: "Hi {{name}}, you are now a {{role}}.
",
});
```
Per-recipient values are also forwarded as `dynamicData` for that recipient, overriding any shared `dynamicData` you pass.
Pass `idempotencyKey` to guarantee a single send for a given logical operation. If your mutation runs twice (Convex retries on conflict), the second call returns the same `emailId` with `deduped: true`.
```ts theme={null}
await autosend.sendEmail(ctx, {
to: ["customer@example.com"],
subject: "Order #1234 confirmation",
html: "Thanks for your order.
",
idempotencyKey: `order:1234:confirmation`,
});
```
Without an explicit key, the component derives one from the payload, so identical payloads also deduplicate.
## Track status and events
The component stores every email and its webhook events in Convex, so you can query them from any Convex query.
```ts convex/emailStatus.ts theme={null}
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 };
},
});
```
Other status helpers:
```ts theme={null}
// 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 });
```
`cancelEmail` only works while the email is in `queued` or `retrying`. Once it reaches `sending`, `sent`, or `failed`, it is locked in.
### Email lifecycle
| Status | Meaning |
| ---------- | --------------------------------------------------- |
| `queued` | Accepted and waiting to be claimed by the processor |
| `sending` | Currently being sent by the queue processor |
| `retrying` | Previous attempt failed and a retry is scheduled |
| `sent` | Accepted by AutoSend |
| `failed` | Retries exhausted or non-retryable error |
| `canceled` | Canceled via `cancelEmail` before send |
Default retry policy is 4 attempts total with delays of 5s, 10s, and 20s. Both are tunable via `maxAttempts` and `retryDelaysMs` in config.
## Configuration
`setConfig` accepts these fields. Anything you omit keeps its existing value (unless you pass `replace: true`).
| Field | Type | Default | Description |
| ----------------- | ---------- | -------------------------- | ------------------------------------------------------ |
| `autosendApiKey` | `string` | unset | Bearer token for the AutoSend API |
| `webhookSecret` | `string` | unset | HMAC secret used to verify incoming webhooks |
| `defaultFrom` | `string` | unset | Fallback sender address when `from` is omitted |
| `defaultReplyTo` | `string` | unset | Fallback reply-to address |
| `testMode` | `boolean` | `true` | Rewrites every recipient to `sandboxTo` |
| `sandboxTo` | `string[]` | `[]` | Recipients used when `testMode` is enabled |
| `rateLimitRps` | `number` | `2` | Max sends per queue run |
| `retryDelaysMs` | `number[]` | `[5000, 10000, 20000]` | Delay schedule between retries |
| `maxAttempts` | `number` | `4` | Total attempts including the first try |
| `sendBatchSize` | `number` | `25` | Max queue items processed per run |
| `autosendBaseUrl` | `string` | `https://api.autosend.com` | API base URL (override for staging) |
| `projectId` | `string` | unset | Required when using an Account API Key (`ASA_` prefix) |
To read the current config (without leaking secrets), use `getConfig`. It returns every value above except `autosendApiKey` and `webhookSecret`, plus `hasApiKey` and `hasWebhookSecret` booleans you can use in admin UIs.
```ts theme={null}
const safeConfig = await autosend.getConfig(ctx);
```
## Overview
The official [AutoSend Convex component](https://www.convex.dev/components/autosend/convex) is a drop-in integration for sending transactional email from your Convex backend. It wraps the AutoSend API with queueing, deterministic idempotency, automatic retries, webhook verification, and full delivery lifecycle tracking, so you only need to call `sendEmail` from a mutation and the component handles the rest.
The package is open source on [GitHub](https://github.com/autosendhq/autosend-convex) and published on [npm](https://www.npmjs.com/package/@autosend/convex) as `@autosend/convex`.