Build with AI
A ready prompt for your coding agent per stack, and these docs as Markdown for any AI tool — llms.txt, llms-full.txt and a .md copy of every page.
Copy a prompt for your agent
Pick your stack, copy the prompt, paste it into your coding agent. The agent
inspects your project, keeps the key in an environment variable, sends from
your server only, puts an idempotency key on every request, sets up a
verified webhook endpoint, and is done when a test email to
delivered@sim.charchy.krd comes back delivered.
The Next.js, Convex and Express prompts use the Node SDK,
@charchy/send (source:
charchyy/charchy-send); Laravel and
Django call the API over HTTP. Each prompt points the agent at the matching
guide where there is one.
# Task: send this app's transactional email through Charchy Send
Charchy Send is Charchy's transactional email API. This app should send its transactional emails — sign-in and verification codes, password resets, receipts, order and booking updates, account notices — through it, from the app's own domain, and react to delivery events (bounces, complaints) with signed webhooks.
The app is built with **Next.js**.
## Before you write code
- Read the full docs first: https://charchy.krd/llms-full.txt (every page as Markdown, plus the OpenAPI file). Follow them over anything you remember about other email APIs.
- Inspect the project. Find every place that sends email today (auth, password reset, checkout, notifications, admin tools), which library it uses, where the templates live, which queue or background-job system exists, and how configuration and secrets are kept.
- Ask the developer **only** for what you cannot find in the code — for example which sending domain is verified, or which emails are marketing. Never ask for the API key itself, and never ask them to paste it into the chat.
- Use the official SDK, `@charchy/send` (zero dependencies, typed): https://charchy.krd/docs/sdks/node. Reuse the rest of what the project has (queue, templates, logger, config).
## How to build it with Next.js
- Install `@charchy/send` and create the client in a server-only module (`lib/charchy-send.ts` starting with `import "server-only"`), made on first use — `export function charchySend() { client ??= new CharchySend(); return client }` — because the constructor throws without a key and `next build` imports route modules. It reads `process.env.CHARCHY_SEND_KEY`: never a `NEXT_PUBLIC_` variable, never in a Client Component.
- Call `charchySend().emails.send()` from server code: Server Actions, Route Handlers, auth callbacks (sign-in codes, password resets), payment webhooks (receipts).
- Don't make the user wait on the email when it isn't the point of the request: send with `after()` from `next/server`, or through the project's queue (Inngest, Trigger.dev, QStash…) if it has one. A sign-in code you send yourself is the exception — send it before answering, so you can show an error if it fails. Better Auth's email callbacks are not: set its `advanced.backgroundTasks.handler` to `after` (https://charchy.krd/docs/guides/better-auth).
- Webhook endpoint: a Route Handler at `app/api/webhooks/charchy/route.ts` — `export const POST = webhookHandler({ "email.bounced": …, "email.complained": … })` from `@charchy/send` when the handlers are quick, or `verifyWebhook({ payload: await request.text(), headers: request.headers })` answering `400` on `WebhookVerificationError` and `204` at once, then the work in `after()` or the queue. No `runtime` export: the Edge runtime is deprecated. Follow https://charchy.krd/docs/guides/nextjs.
## Rules
- **The key is a secret, and lives on the server only.** Read it from `CHARCHY_SEND_KEY`. Never put it in browser or mobile code, a public repository, a committed `.env`, logs or error messages. The API sends no CORS headers, so browser code can't use it anyway. Add `CHARCHY_SEND_KEY=`, `CHARCHY_SEND_FROM=` and `CHARCHY_WEBHOOK_SECRET=` (empty) to the project's example env file if it has one. The developer creates keys in the Charchy dashboard under API keys: `chy_test_…` for development and CI, `chy_live_…` for production.
- **Endpoint:** `send.emails.send({ from, to, subject, html, … })` (the SDK's fields are the API's in camelCase: `replyTo`, `scheduledAt`, `expiresAt`), which calls `POST https://api.charchy.krd/v1/emails` with `Authorization: Bearer $CHARCHY_SEND_KEY` and a JSON body: `from`, `to` (array), `subject`, `html` and/or `text`, optional `cc`, `bcc`, `reply_to`, `tags`, `attachments`, `scheduled_at`, `expires_at`. Up to 100 different emails at once: `POST https://api.charchy.krd/v1/emails/batch` with `{ "emails": [...] }`. Keep the returned `id` with the record the email belongs to.
- **`from`** is read from `CHARCHY_SEND_FROM` (e.g. `"My App <no-reply@myapp.com>"`) and must be on a domain verified in the developer's workspace. Kurdish and Arabic display names are fine.
- **An `Idempotency-Key` on every request** (the SDK's `{ idempotencyKey }` option, the second argument of `send.emails.send`), made from the event that causes the email (`password-reset-<token id>`, `order-<id>-confirmation`, the job id) — never a random value made inside the retry loop. Retries are the main cause of duplicate emails.
- **Retries:** the SDK already retries network errors, `5xx`, `429` (after `Retry-After`) and `409 idempotency_in_flight` with the same key — don't wrap it in another retry loop. Its methods return `{ data, error }` and never throw: when `error` is set (`402 insufficient_balance` or any other `4xx`, or retries ran out), log `error.code`, `error.docs` and `error.requestId` loudly.
- **Codes that expire** (sign-in, verification, one-time passwords) get `expires_at` set to the code's own expiry, so a late code is dropped instead of delivered.
- **Transactional only.** Newsletters, offers and announcements must not go through this API (they belong in Charchy Campaigns). If the project sends marketing email, leave it where it is and tell the developer.
- **Webhooks:** add an HTTPS endpoint that verifies the Standard Webhooks signature (headers `webhook-id`, `webhook-timestamp`, `webhook-signature`; secret `CHARCHY_WEBHOOK_SECRET`, starting `whsec_`) against the **raw** request body, rejects timestamps more than 5 minutes old, answers `2xx` within 5 seconds and does the work afterwards, ignores a `webhook-id` it has already processed, and never assumes events arrive in order (use `created_at`). On `email.bounced` and `email.complained`, mark the address so the app can ask the user to fix it. The developer adds the endpoint's URL in the dashboard under Webhooks.
- Keep the mapping from the app's events to the email JSON in one place, and test it if the project has tests.
## Definition of done
1. With a test key, `POST https://api.charchy.krd/v1/emails` to `delivered@sim.charchy.krd` answers `200` with an `id` — sent through the code you wrote, from a real trigger in the app (for example a password reset).
2. `GET https://api.charchy.krd/v1/emails/<id>` shows it `delivered` a moment later.
3. Repeating the same request with the same `Idempotency-Key` returns the same `id` and sends nothing new.
4. The webhook endpoint receives `email.delivered` for that email, verifies its signature, and rejects a request with a changed body. Sending to `bounced@sim.charchy.krd` exercises the bounce path.
5. Tell the developer what you built, which environment variables to set (`CHARCHY_SEND_KEY`, `CHARCHY_SEND_FROM`, `CHARCHY_WEBHOOK_SECRET`), which webhook URL to add in the dashboard, and that a live key and a verified domain are needed before real customers get these emails.
## Reference
- Full docs as Markdown: https://charchy.krd/llms-full.txt
- Map of the docs: https://charchy.krd/llms.txt
- OpenAPI 3.1: https://charchy.krd/docs/openapi.yaml
- Errors, one section per code: https://charchy.krd/docs/errors
Stack not listed? Any prompt works as a start: the agent reads the full docs
from llms-full.txt before it writes code.
These docs as Markdown
| Address | What it is |
|---|---|
/llms.txt | A map of the docs: every page, with a link to its Markdown |
/llms-full.txt | Every page in one file, plus the OpenAPI file |
/docs/<page>.md | Any page as Markdown — e.g. /docs/quickstart.md |
/docs/openapi.yaml | The OpenAPI 3.1 contract |
Any docs page requested with Accept: text/markdown returns Markdown, so
agents never parse HTML.
On every page
Under each page's title:
- Copy page copies the page as Markdown.
- Open in ChatGPT and Open in Claude start a chat that reads the page first, so answers come from these docs, not from memory.
Keep your key out of the chat
Your agent never needs your API key. The prompts tell it to read
CHARCHY_SEND_KEY from the environment and never ask you for it — set it
yourself, in your .env or your host's secret settings.