Hoe implementeert een productteam de e-mail-API van Resend veilig?

Definieer de productbewerking vóór het providerrequest

Begin met een afgebakende bewerking in je applicatie, zoals accountverificatie, een ontvangstbewijs, een beveiligingsmelding of een notificatie waar de ontvanger om heeft gevraagd. Het openbare endpoint van je product moet de aanroeper, tenant, berichtklasse, afzenderidentiteit, ontvangers en template autoriseren voordat er een Resend-payload bestaat. Laat een browser geen willekeurige `from`, `to`, HTML of provideropties indienen terwijl die over een herbruikbare credential beschikt. Maak een duurzaam intern record voor uitgaande berichten aan met een applicatie-eventsleutel, tenant, templaterevisie, goedgekeurde afzender, set ontvangers en de huidige status. Een worker kan dat record vertalen naar het providerrequest. Deze grens houdt API-sleutels en onbetrouwbare berichtinhoud weg bij clients, maakt het voorkomen van duplicaten testbaar en stelt het product in staat van provider te wisselen zonder elke zakelijke workflow te herschrijven. Scheid in het interne model transactionele berichten en berichten die van toestemming afhangen, zodat voorkeuren, suppressies en beslissingen bij incidenten expliciet blijven.

Verifieer het exacte domein in het From-adres

Voeg in Resend een domein toe dat je beheert en publiceer de DNS-records die voor dat domein worden getoond. Verifieer het werkelijke organisatiedomein of subdomein dat in het zichtbare From-adres wordt gebruikt, in plaats van aan te nemen dat een los bovenliggend domein het dekt. Bekijk het bestaande SPF- en DMARC-beleid voordat je DNS wijzigt, en maak nooit een tweede SPF-record aan voor dezelfde hostnaam. Gebruik een apart verzendsubdomein als isolatie, eigenaarschap of migratie-eisen dat rechtvaardigen. Bekijk nadat het dashboard de verificatie meldt een ontvangen testbericht om het zichtbare From-adres, de DKIM-ondertekeningsidentiteit, het return path, de authenticatieresultaten en het antwoordgedrag te controleren. Verificatie door de provider bewijst dat een geconfigureerde identiteit door de configuratiecontrole van de provider is gekomen. Het bewijst geen toestemming van ontvangers, acceptatie door de ontvangende server, inboxplaatsing of een goede reputatie. Houd het DNS-eigenaarschap en de wijzigingsgeschiedenis buiten het providerdashboard bij, zodat rotatie en rollback mogelijk blijven.

Maak per workload een API-sleutel met minimale rechten

Resend documenteert API-sleutels met toegangsniveaus en een optionele beperking tot een domein. Een verzendworker hoort een sleutel te gebruiken die beperkt is tot verzendrechten en, als de architectuur het toelaat, tot het ene domein waarvan die workload eigenaar is. Houd beheer van domeinen, webhooks en het account onder aparte bevoegdheden. Maak aparte sleutels voor development, staging en productie, zodat een lagere omgeving niet met de productie-identiteit kan verzenden of de limieten van productie kan verbruiken. Sla elk secret direct op in een beheerde secret store, stel het alleen beschikbaar aan het serverproces dat het nodig heeft en geef het via HTTPS mee als Bearer-autorisatie. Kopieer de sleutel niet naar versiebeheer, buildartefacten, logs, templates, analytics, tickets of prompts. Oefen de rotatie: maak een vervanging met dezelfde scope, werk de worker bij, controleer gecontroleerd verkeer en de koppeling van events, en trek daarna de oude sleutel in. Stel meldingen in bij onverwachte authenticatie- en autorisatiefouten, want die kunnen wijzen op verlopen, ingetrokken of verschoven scopes, of op een gelekt secret.

Maak één duurzame job en één idempotente verzendpoging

Reserveer de interne uitgaande job voordat je Resend aanroept. Leid een idempotentiewaarde af van een stabiel productgegeven, zoals tenant, type bewerking en een onveranderlijk applicatie-event-ID, niet van een willekeurige retrypoging. Stuur die waarde mee in de header `Idempotency-Key`. Resend documenteert momenteel dat deze sleutels dubbele e-mailrequests voorkomen, na 24 uur verlopen en maximaal 256 tekens mogen bevatten. Dat venster van de provider helpt, maar is geen volledige garantie tegen duplicaten op productniveau. Houd voor langere zakelijke workflows een uniciteitsbeperking aan op de interne eventsleutel, serialiseer workers die dezelfde job kunnen oppakken en sla het e-mail-ID op dat een geslaagd request teruggeeft. Als een netwerktimeout de acceptatie onduidelijk maakt, houd de job dan in een onbekende status en reconcilieer die met de logs of events van de provider voordat je opnieuw verstuurt. Eén stabiele sleutel hergebruiken voor dezelfde logische bewerking is veiliger dan voor elke transport-retry een nieuwe sleutel genereren.

Stel het e-mailrequest bewust samen en valideer het

Het send-email-endpoint van Resend accepteert een From-adres, ontvangers, een onderwerp en berichtinhoud, met gedocumenteerde opties zoals text, HTML, met React gerenderde content, templates, Cc, Bcc, reply-to, headers, bijlagen, tags en geplande bezorging. Stel alleen de subset beschikbaar die het product nodig heeft. Valideer de syntaxis van adressen en het eigenaarschap door de tenant, houd het aantal ontvangers en bijlagen onder de limieten van de provider, weiger newline-injectie in headers en bouw MIME-gerelateerde content op via onderhouden bibliotheken of vertrouwde providervelden. Zet geen credentials, gevoelige persoonsgegevens of onbeperkte klantinvoer in tags of headers. Sla een templaterevisie en opgeschoonde variabelen op in plaats van de volledige inhoud te loggen. Een interne adapter hoort een beperkt resultaat terug te geven, zoals een geaccepteerd provider-ID of een geclassificeerde fout, en geen details van de providerrespons naar de businesscode te lekken. Zo kun je providerspecifieke veldnamen, SDK-versies of requestlimieten bijwerken zonder het contract van de productevents te wijzigen.

Classificeer API-responses en gebruikslimieten voordat je opnieuw probeert

Beschouw de HTTP-respons als één waarneming in de workflow. Een geslaagde verzendrespons geeft een e-mail-identifier terug die je bij de interne job moet opslaan, maar bewijst geen acceptatie door de bestemming of inboxplaatsing. Herstel validatie-, authenticatie-, domein-, rechten- en payloadfouten in plaats van ze blind opnieuw te proberen. Resend documenteert limieten voor API-requests en geeft headers voor rate limits en quota terug, met velden voor de resterende capaciteit, het resetmoment en de retryvertraging; bij een 429-respons wacht je het gedocumenteerde interval af, met extra jitter. Probeer transportfouten en geschikte serverfouten opnieuw met exponential backoff, een eindig aantal pogingen en dezelfde logische idempotentiesleutel zolang het gedocumenteerde venster geldt. Onduidelijke fouten vragen om reconciliatie, want de provider kan de e-mail hebben geaccepteerd ook als de client de respons niet heeft ontvangen. Stel meldingen in wanneer herhaalde fouten zich concentreren per domein, template, sleutel of tenant, maar houd credentials, volledige content en onnodige ontvangergegevens uit operationele logs.

Authenticeer webhookrequests voordat je events verwerkt

Configureer een apart HTTPS-webhookendpoint en bewaar de exacte ruwe request body. Resend documenteert webhookondertekening via Svix-compatibele headers en signing secrets. Verifieer het webhook-ID, het tijdstempel en de handtekening over de ongewijzigde payload vóór het parsen of opnieuw serialiseren van JSON, en gebruik de officiële verificatieflow of een onderhouden compatibele bibliotheek. Weiger ongeldige of verouderde requests, begrens de requestgrootte en houd het signing secret gescheiden van de verzendsleutel. Sla het event na authenticatie duurzaam op of zet het in de wachtrij voordat je het bevestigt, zodat een procescrash bezorgbewijs niet ongemerkt weggooit. Bezorgsystemen kunnen webhooks opnieuw versturen en dupliceren, dus gebruik de event-identifier als deduplicatiesleutel en maak statusovergangen monotoon. Een later of dubbel event mag een informatiever eindresultaat niet overschrijven alleen omdat het als laatste binnenkwam. Leg verificatiefouten en eventvertraging vast als operationele signalen, zonder ruwe berichtinhoud langer te bewaren dan de noodzakelijke bewaartermijn.

Modelleer provider-events zonder bezorging te overdrijven

Resend publiceert benoemde e-maileventtypen, waaronder sent, delivered, delivery delayed, bounced, complained, failed, opened en clicked. Koppel die providernamen aan een intern statusmodel met het oorspronkelijke eventtype, het e-mail-ID van de provider, het event-ID, het tijdstempel, de ontvangersscope en de beschikbare diagnosegegevens. Een sent-event beschrijft voortgang bij de provider. Een delivered-event meldt bezorging volgens de gedocumenteerde eventsemantiek van Resend, maar SMTP-succes bij een ontvangend systeem zegt nog steeds niets over de uiteindelijke map bij de ontvanger. Opens en clicks zijn waarnemingen van engagement, geen bewijs van bezorging, en privacytechnologie kan ze beïnvloeden. Bounces, klachten en permanente fouten moeten de veiligheidsstatus van de ontvanger bijwerken vóór de volgende verzendbeslissing. Houd de eventgeschiedenis van de provider append-only en leid de status die gebruikers zien af via expliciete regels. Zo blijft bewijs voor support bewaard en voorkom je onveilige retries nadat de verantwoordelijkheid is overgedragen of een ontvanger een negatief signaal heeft gegeven.

Test faal- en herstelpaden met ontvangers die je zelf beheert

Gebruik een sleutel die niet voor productie is, een gecontroleerd geverifieerd subdomein en mailboxen van het team. Test tekst- en HTML-content, reply-to-gedrag, limieten voor bijlagen, stabiele idempotentiesleutels en opgeslagen provider-identifiers. Dien dezelfde logische job twee keer in en controleer dat de controles van de applicatie en de provider geen onbedoeld duplicaat opleveren. Test een ongeldige payload, een verkeerd domein, een ingetrokken sleutel, onvoldoende rechten, een rate limit, een transporttimeout, een bounce, een klacht, een vertraagde bezorging, een gedupliceerde webhook, een gewijzigde body bij de handtekening, een verouderd webhooktijdstempel en rotatie van het signing secret. Controleer dat de ontvangst van events duurzaam is vóór de bevestiging en dat de veiligheidsstatus van een ontvanger een latere job blokkeert. Test DNS-rotatie en het verwijderen van de provider zonder niet-gerelateerde records te wissen. Dashboards moeten verzendfouten, latentie, fouten bij webhookverificatie, eventvertraging, bounces, klachten en reconciliatiewachtrijen tonen. Bekijk bij de lancering de actuele documentatie en accountinstellingen van Resend, want quota, limieten, eventvelden en beschikbare rechten kunnen veranderen los van de gedeployde applicatiecode.

Vergelijk gepubliceerde API-mogelijkheden voordat je migreert

SendHQ publiceert een OpenAPI 3.1-contract voor de e-mail-API per workspace, inclusief verzending vanaf geverifieerde domeinen, inkomende e-mail, gehoste templates, bezorgevents en suppressies. Vergelijk vóór je een integratie migreert request bodies, authenticatie, idempotentie, geretourneerde identifiers, foutvormen, webhooks, domeinregels en suppressiegedrag en valideer deze vervolgens met tests op veldniveau. Ga niet uit van compatibiliteit op basis van vergelijkbare endpointnamen.

Veelgestelde vragen

Bronnen

• Resend Send Email API — Resend
• Resend API Keys — Resend
• Resend Domains — Resend
• Resend Idempotency Keys — Resend
• Resend Usage Limits — Resend
• Resend Webhooks — Resend
• Verify Resend Webhook Requests — Resend
• Resend Webhook Event Types — Resend
• RFC 5321: Simple Mail Transfer Protocol — RFC Editor
• OpenAPI-contract van SendHQ — SendHQ