Erste Schritte

Von Resend migrieren

Übertragen Sie Resend-HTTP-Sendungen auf SendHQ und berücksichtigen Sie die Kompatibilitätsgrenzen vor der Umstellung.

Kompatibilitätsgrenze

SendHQ akzeptiert die üblichen JSON-Felder im Resend-Stil für direkte HTTP-Sendungen, ist aber kein Drop-in-Ersatz für das Resend-SDK. Richten Sie Ihren eigenen serverseitigen HTTP-Adapter auf /api/v1/emails aus; gehen Sie nicht davon aus, dass sich ein SDK mit fest codiertem Resend-Host umkonfigurieren lässt.

Feldzuordnung

from, to, cc, bcc, subject, html, text, reply_to und sichere benutzerdefinierte headers werden direkt übernommen. SendHQ akzeptiert außerdem message_class, Referenzen auf gehostete template-Templates, draft_id sowie Antwort- und Thread-Felder. Resend-spezifische React-Payloads, Inline-Anhang-Arrays, Tags, Audiences, Broadcasts und Felder für geplanten Versand werden nicht als gleichwertig akzeptiert.

Anhänge und Templates

Laden Sie Anhänge in einen SendHQ-Entwurf hoch und senden Sie dann mit draft_id. Gehostete Templates sind SendHQ-Ressourcen mit veröffentlichten Versionen und typisierten Daten; migrieren Sie Template-IDs und Rendering-Aufrufe explizit, statt eine Template-Kennung des Providers zu kopieren.

Wiederholungsversuche

Erzeugen Sie pro logischer Sendung einen stabilen Idempotency-Key. Wiederholen Sie das identische JSON-Payload mit diesem Schlüssel. Ändert sich Betreff, Inhalt, Empfänger, Header oder Template-Daten, verwenden Sie einen neuen Schlüssel; andernfalls liefert SendHQ 409. Eine erneut ausgelieferte gespeicherte Antwort enthält Idempotent-Replayed: true.

Checkliste für die Umstellung

  1. Verifizieren Sie jede From-Domain und jede exakte Absenderadresse, die Sie verwenden werden.
  2. Senden Sie kontrollierte Text- und HTML-Nachrichten an ein eigenes Postfach.
  3. Prüfen Sie die Annahme durch den Provider getrennt von den Zustell-Events.
  4. Testen Sie die Behandlung von 409, 422, 423, 429 und 5xx.
  5. Halten Sie den Adapter des bisherigen Providers bereit, bis sowohl die transaktionalen als auch die Lifecycle-Pfade bestehen.

Hand this to your coding agent

Paste this into Claude Code, Cursor, Codex, or another coding agent at the root of your repository. It is self-contained: it lists the SendHQ endpoints, fields, and limits so the agent does not have to guess, and it asks for a report of anything it could not map. Review the diff like any other change, and register the webhook URL and DNS records yourself.

Prompt for your coding agent
Migrate this codebase from Resend to SendHQ. Keep user-visible behaviour identical. Do not send real email, change DNS, or call production APIs while working.

STEP 1: INVENTORY
Search the whole repository (application code, workers, scripts, infrastructure as code, CI config, .env examples, docs) for every use of Resend, including: the resend npm and Python packages (new Resend(...).emails.send, resend.Emails.send, resend.batch / emails/batch, resend.webhooks.verify), raw HTTP calls to api.resend.com, SMTP transports pointed at smtp.resend.com, React Email components passed as react, RESEND_* env vars, and Svix-signed webhook handlers (svix-id, svix-timestamp, svix-signature). Note: SendHQ keys also start with re_, so identify Resend usage by host, package, and env var name, not by key prefix.
List each call site with: what it sends (transactional, marketing, inbound handling), the Resend features it uses (react payloads, attachments, tags, scheduled_at, templates, batch sends, idempotency keys, webhooks, received email), and the env vars it reads.

STEP 2: SENDHQ API FACTS (use exactly these; do not guess or invent other endpoints)
- Base URL: https://sendhq.cc/api/v1
- Auth: header "Authorization: Bearer <SENDHQ_API_KEY>". Keys start with re_. Server side only, never in browser or mobile code.
- There is no SendHQ SDK, no SMTP relay, and no Resend-compatible endpoint. Call the REST API with the project's existing HTTP client (fetch, axios, requests, httpx, net/http, ...).
- Send one: POST /emails, Content-Type: application/json. Fields:
  from (string, "Name <addr@verified-domain>", required; the domain must be verified in SendHQ)
  to (string or array of strings, required), cc, bcc (string or array). At most 100 addresses across to+cc+bcc.
  subject (string), html (string), text (string). One of html, text, or template is required.
  reply_to (ONE address string, not an array)
  headers (object of string to string; not allowed: From, To, Cc, Bcc, Subject, Date, Message-ID, In-Reply-To, References, Content-Type, MIME-Version)
  message_class ("transactional" default, or "marketing", which adds SendHQ's unsubscribe link and headers unless you supply your own one-click List-Unsubscribe)
  template ({"key": "...", "data": {...}} or {"id": "tmpl_..."}; not combinable with subject/html/text; exactly one to and no cc/bcc)
  draft_id (attachments, see below), reply_to_email_id (thread a reply), labels (array of up to 10 mailbox label names)
  Response 201: {"id": "em_...", "providerMessageId": "...", "threadId": "..."}. Persist id.
- Unknown fields (tags, metadata, categories, custom variables, scheduled times, tracking flags) are ignored. Do not send them.
- Idempotency: header "Idempotency-Key" (max 200 chars), one stable key per logical send. Retrying the identical body with the same key replays the stored response (response header Idempotent-Replayed: true). Same key with a different body returns 409.
- Batch: POST /emails/batch {"emails": [ ...up to 100 send objects ]} returns 201 or 207 with {"data": [{"index", "ok", "id"} or {"index", "ok": false, "error": {"message", "status"}}], "count", "successful", "failed"}.
- Attachments: POST /drafts {"from", "to", "subject"} returns {"id": "dr_..."}; then for each file POST /drafts/{id}/attachments with the raw bytes as the body, header Content-Type: <mime type> and X-Filename: <name>; then POST /emails with "draft_id": "dr_...". Max 10 files and 10 MB per message. No inline/CID images.
- Errors: JSON {"error": {"message", "status", "code"?}}. 400 invalid input, 401 bad key, 402 subscription_required (no active plan; do not retry), 403 domain not verified or not owned, 404 missing resource, 409 idempotency conflict, 413 attachments too large, 422 recipient suppressed or unsubscribed, 423 sender_paused or account_paused, 429 daily_limit_reached (wait until resets_at / Retry-After, midnight UTC, not a short backoff; the message was not queued), hourly_limit_reached (next UTC hour), gmail_recipient_limit (midnight UTC), or quota_exhausted. Retry 502/503 with backoff and the same Idempotency-Key and identical body.
- Webhooks: create with POST /webhooks {"url": "https://...", "events": [...]}; the response has "secret": "whsec_...". Event types: email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received. One JSON event per request: {"type", "created_at", "data"}; data has email_id, from, to, subject, and per type: delivered -> recipients; delivery_delayed -> recipients, delay {type, diagnostic, expiration}; bounced -> recipient, bounce {type "Permanent"|"Transient", sub_type, diagnostic, suppressed}; complained -> recipient, complaint {feedback_type}; failed -> reason; received -> inbox_id, category. No open, click, or unsubscribe events.
  Verify Standard Webhooks signatures on the RAW body: headers webhook-id, webhook-timestamp, webhook-signature ("v1,<base64>", space separated if several). Expected = base64(HMAC-SHA256(key = base64-decode(secret without "whsec_"), message = "{webhook-id}.{webhook-timestamp}.{raw body}")). Constant-time compare, reject timestamps older than 5 minutes, dedupe on webhook-id, return 2xx within 10 seconds.
- Suppressions: SendHQ suppresses permanent bounces and complaints itself (GET /suppressions, GET /blocked-recipients). There is no import endpoint.
- Templates: POST /templates {"name", "key"}; PUT /templates/{id}/draft {"revision", "name", "subjectTemplate", "htmlTemplate", "textTemplate", "variables": [{"key", "type": "text"|"number"|"url"|"boolean", "required"}], "sampleData"}; POST /templates/{id}/render {"data"}; POST /templates/{id}/publish. Only {{variable}} substitution with lowercase_snake_case keys: no conditionals, loops, partials, or nested objects.
- Inbound: POST /domains/{id}/inbound/setup returns the MX record to publish; POST /inboxes {"domain_id", "local_part", "name"} creates an address; an email.received webhook carries data.email_id and data.inbox_id; GET /emails/{id} returns from, to, subject, html, text, and attachments (download with GET /attachments/{id}). Mail is stored, not forwarded to your URL.
- Full contract: https://sendhq.cc/openapi.json and https://sendhq.cc/docs/resend-migration

STEP 3: FIELD MAPPING FROM RESEND
- Change the host and adapter: https://api.resend.com/emails -> https://sendhq.cc/api/v1/emails. The SDK cannot be pointed at SendHQ; replace SDK calls with direct HTTP calls in the adapter.
- from, to, cc, bcc, subject, html, text, headers keep their names. reply_to (Node SDK: replyTo) -> reply_to, one address.
- react -> render the component to an HTML string (and a text version) in your code, then send html/text.
- attachments (content or path) -> fetch/decode each file, upload to a draft, send with draft_id. content_id inline images -> not supported, report.
- tags, scheduled_at (scheduledAt) -> not supported; remove and report.
- template {id, variables} -> template {"key": "<SendHQ template key>", "data": variables}.
- Idempotency-Key header -> same header name; keep keys at 200 characters or fewer.
- POST /emails/batch (up to 100) -> same path and limit, but the SendHQ response is {"data": [{"index", "ok", "id" | "error"}], ...}; check ok per item.
- Response {id} -> {"id": "em_...", "providerMessageId", "threadId"}.
- Webhooks: replace Svix verification (svix-id/svix-timestamp/svix-signature, resend.webhooks.verify) with Standard Webhooks verification (webhook-id/webhook-timestamp/webhook-signature). email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received keep their names; data.bounce {type, subType, message} -> data.bounce {type, sub_type, diagnostic}; email.opened, email.clicked, email.scheduled, email.suppressed, contact.*, domain.* and other events have no SendHQ equivalent, report the handlers.
- email.received: Resend fetches content from /emails/receiving/{id}; in SendHQ use GET /emails/{data.email_id}.

STEP 4: IMPLEMENT
- Create one SendHQ email adapter module with the same function signatures the app already uses, so call sites change as little as possible. Read the key from SENDHQ_API_KEY.
- Keep the Resend implementation behind a switch (for example EMAIL_PROVIDER=sendhq|resend, optionally per stream) so the team can run both and roll back. Default it to resend.
- Env vars: add SENDHQ_API_KEY and SENDHQ_WEBHOOK_SECRET to every .env example, config schema, secret manifest, and deployment config where RESEND_API_KEY and RESEND_WEBHOOK_SECRET (or however the project names them) appear. Do not delete the Resend variables yet.
- Generate one Idempotency-Key per logical send from data you already have (for example "<event>-<record id>") and reuse it on retries.
- Webhooks: add a SendHQ webhook route next to the existing Resend handler. Map SendHQ events onto the same internal handlers (for example email.delivered, email.bounced, email.complained). Correlate by the em_ id you stored at send time, not by Resend message IDs.
- Suppressions: keep honouring the existing Resend suppression data (export it to the app's database if the app does not already store it) and check it in the adapter before sending.
- SMTP senders: replace each SMTP transport that targets smtp.resend.com with the HTTP adapter; SendHQ has no SMTP relay.

STEP 5: TESTS
- Unit-test the adapter with a mocked HTTP client: exact URL, method, headers (Authorization, Content-Type, Idempotency-Key) and JSON body for a plain send, cc/bcc, reply_to, custom headers, a template send, a batch, and an attachment send (draft, upload, send with draft_id).
- Test error handling for 401, 409, 422, 423, 429 and 503, and that only 429/502/503 are retried with the same key.
- Test the webhook route: a valid signature is accepted, a tampered body, an old timestamp, and a wrong secret are rejected, a repeated webhook-id is processed once, and each event type reaches the right internal handler.
- Run the existing test suite and keep it green.

STEP 6: REPORT
Finish with a list of everything you could not map one-to-one, with file paths, for example: React Email payloads that need a render step, tags, scheduled sends, open/click handlers, contact and domain events, inline images, SMTP senders. Also list the env vars added, the webhook URL to register in SendHQ, and the DNS records the team must add by hand. Do not remove Resend code or credentials; the team will do that after cutover.