Primeros pasos

Migrar desde Resend

Traslade los envíos HTTP de Resend a SendHQ y tenga en cuenta los límites de compatibilidad antes del cambio.

Límite de compatibilidad

SendHQ acepta los campos JSON habituales al estilo de Resend para envíos HTTP directos, pero no es un reemplazo directo del SDK de Resend. Apunte su propio adaptador HTTP del lado del servidor a /api/v1/emails; no dé por hecho que un SDK con el host de Resend fijado en el código pueda reconfigurarse.

Correspondencia de campos

from, to, cc, bcc, subject, html, text, reply_to y los headers personalizados seguros se asignan directamente. SendHQ también acepta message_class, referencias a template alojadas, draft_id y campos de respuesta/hilo. Los payloads de React específicos de Resend, los arrays de adjuntos en línea, las etiquetas, las audiencias, las difusiones y los campos de envío programado no tienen equivalentes aceptados.

Adjuntos y plantillas

Suba los adjuntos a un borrador de SendHQ y después envíe con draft_id. Las plantillas alojadas son recursos de SendHQ con versiones publicadas y datos tipados; migre explícitamente los ID de plantilla y las llamadas de renderizado en lugar de copiar el identificador de plantilla de un proveedor.

Reintentos

Genere una Idempotency-Key estable por cada envío lógico. Reintente el payload JSON idéntico con esa clave. Si cambian el asunto, el cuerpo, un destinatario, un encabezado o los datos de la plantilla, use una clave nueva; de lo contrario, SendHQ devuelve 409. Una respuesta almacenada que se reproduce incluye Idempotent-Replayed: true.

Lista de comprobación para el cambio

  1. Verifique cada dominio From y cada dirección de remitente exacta que vaya a usar.
  2. Envíe mensajes controlados de texto y HTML a una bandeja de entrada propia.
  3. Confirme la aceptación por el proveedor por separado de los eventos de entrega.
  4. Pruebe la gestión de 409, 422, 423, 429 y 5xx.
  5. Mantenga disponible el adaptador del proveedor anterior hasta que funcionen tanto los flujos transaccionales como los de ciclo de vida.

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.