gids · e-mail-api

Hoe implementeert een productteam een e-mail-API veilig?

Implementeer een e-mail-API als een asynchrone workflow met rechtencontrole, niet als een directe aanroep van formulier naar provider. Authenticeer de aanroeper, bevestig dat de tenant eigenaar is van een geverifieerd From-domein, valideer het bericht en controleer de grootte, ken een stabiele job-ID in de applicatie toe, zet het bericht één keer in de wachtrij en verstuur het vanuit een worker. Leg bij acceptatie het bericht-ID van de provider vast, verwerk bezorgevents idempotent en zet permanente bounces en klachten op de suppressielijst. Gebruik alleen begrensde retries als het risico op duplicaten beheerst is. Houd credentials server-side, beperk berichtdata in logs tot het minimum en maak onderscheid tussen acceptatie door de API, aflevering bij de mailserver en inboxplaatsing.

Bepaal de API-grens voordat je een provider kiest

Een e-mail-API hoort de bedoeling van de applicatie bloot te leggen zonder elk providerdetail in de productcode te laten doorsijpelen. Definieer resources voor berichten, verzenddomeinen, API-sleutels, events en suppressies. Bepaal welke velden aanroepers mogen instellen, zoals From, To, Reply-To, onderwerp, tekst, HTML en een kleine allowlist van headers. Weiger transportheaders van de aanroeper die kunnen botsen met de ondertekening of routering van de provider. Behandel verzenden als een schrijfactie met gevolgen: de respons moet een berichtresource in de applicatie en de huidige status ervan aanwijzen, niet een uitkomst in de mailbox suggereren. Houd het provideraccount, de Region, de configuration set en transport-identifiers achter een adapter. Met deze grens wordt migreren naar een andere provider mogelijk en krijgen autorisatie, bewaartermijnen en maatregelen tegen misbruik een stabiele plek.

Authenticeer aanroepers en autoriseer elk afzenderdomein

Sla API-sleutels alleen op als eenrichtingshash en toon het volledige geheim één keer. Geef elke sleutel een workspace-eigenaar, status, aanmaaktijd en intrekkingspad; voeg smallere scopes toe als een integratie alleen mag verzenden of alleen events mag lezen. Authenticatie beantwoordt wie een credential heeft aangeboden, terwijl autorisatie bepaalt of die principal het gevraagde From-domein en de berichtresource mag gebruiken. Controleer het domeineigendom bij elke verzending, ook bij batch-endpoints, in plaats van te vertrouwen op een domein-ID die de client meestuurt. Vereis verificatie bij de provider voordat je productieverkeer inschakelt. Zet provider-credentials of API-sleutels van workspaces nooit in JavaScript in de browser, querystrings, analytics of foutmeldingen. Autorisatie op objectniveau is extra belangrijk voor identifiers van berichten, events, suppressies, inboxen en domeinen in een multi-tenant API.

Verifieer het domein en aligneer de authenticatie

Een verzenddomein heeft meer nodig dan een vlag in de database. Voltooi de eigendomscontrole van de provider en publiceer de vereiste DKIM-records. SPF autoriseert hosts voor de SMTP MAIL FROM- of HELO-identiteit, terwijl DKIM een ondertekeningsdomein koppelt aan een cryptografische handtekening op het bericht. DMARC beoordeelt of een geslaagde SPF- of DKIM-identifier aligned is met het zichtbare From-domein uit RFC 5322 en laat een domeineigenaar beleid voor afhandeling en rapportage publiceren. Heeft een domein al SPF, voeg dan het vereiste mechanisme samen in het bestaande record; RFC 7208 stelt dat een domein geen meerdere records mag publiceren waardoor meer dan één SPF-record wordt geselecteerd. Voer strenger DMARC-beleid pas in als gecontroleerde berichten en geaggregeerde rapporten laten zien dat elke legitieme afzender aligned is. Authenticatie vermindert onbevoegd gebruik van je domein, maar garandeert geen inboxplaatsing.

Valideer de berichtstructuur en accepteer zo min mogelijk invoer

RFC 5322 definieert een internetbericht als headervelden gevolgd door een optionele body, waarbij MIME-specificaties de inhoud uitbreiden tot voorbij eenvoudige tekst. Een API kan de meeste details van het wire format verbergen en ze toch afdwingen. Normaliseer ontvangerarrays, begrens het aantal ontvangers en de totale gecodeerde grootte, vereis minstens één tekst- of HTML-body en valideer adressen zonder te doen alsof correcte syntaxis bewijst dat de mailbox bestaat. Verwijder carriage-return- en line-feed-tekens uit velden die headers worden. Genereer de Message-ID zelf of laat de provider dat doen; hergebruik hem niet als job-ID in de applicatie, want een nieuwe versie van een bericht kan terecht een nieuwe identifier krijgen. Sta alleen gedocumenteerde aangepaste headers toe, weiger duplicaten van beschermde velden en render templates vóór het indienen bij de provider, zodat ontbrekende variabelen falen in een gecontroleerde applicatiestatus.

Zet het bericht één keer in de wachtrij en gebruik stabiele identifiers

Een gebruikersverzoek hoort in een transactie één duurzame berichtjob aan te maken, waarna een worker de aanroep naar de provider doet. Geef de job een stabiele identifier en leg een request-fingerprint vast, of een idempotentiesleutel van de aanroeper als het contract die ondersteunt. HTTP definieert POST standaard als niet-idempotent en waarschuwt tegen automatische retries, tenzij de client weet dat de bewerking feitelijk idempotent is of weet dat het oorspronkelijke request niet is uitgevoerd. Dat is belangrijk bij e-mail, want een timeout kan optreden nadat de provider het bericht heeft geaccepteerd maar voordat de worker de respons heeft ontvangen. Reconcilieer bij een dubbelzinnige fout eerst de opgeslagen job met de status bij de provider, in plaats van een nieuwe verzending aan te maken. Gebruik een outbox-patroon als applicatiestatus en publicatie naar de wachtrij samen moeten gebeuren, en leg een uniciteitsconstraint op de idempotentiegrens.

Ontwerp retries rond foutklassen

Maak onderscheid tussen validatie, autorisatie, throttling, weigering door de provider, tijdelijke transportfouten en bezorgfouten bij de ontvanger. Ongeldige invoer en een niet-geautoriseerd From-domein moeten falen zonder retry. Rate limits van de provider en tijdelijke servicefouten kun je opnieuw proberen met begrensde exponential backoff, jitter, een maximum aantal pogingen en een visibility timeout van de wachtrij die langer is dan de requestdeadline van de worker. Een dubbelzinnige netwerktimeout vraagt om reconciliatie met oog voor duplicaten, niet om een onvoorwaardelijk nieuw request. SMTP maakt zelf onderscheid tussen tijdelijke 4xx- en permanente 5xx-antwoorden, maar een applicatie die de API van een provider gebruikt, volgt de gedocumenteerde foutsemantiek van die provider. Verplaats uitgeputte jobs naar een dead-letter-status die je kunt beoordelen en bewaar de opgeschoonde reden. Probeer een permanente bounce van een ontvanger niet opnieuw alsof het een API-storing was, en maak van een klacht geen nieuwe verzendpoging.

Leg acceptatie vast en verwerk bezorgevents

Bewaar de berichtidentifier van de provider direct na acceptatie en koppel deze aan de bericht-ID van de applicatie. Providerevents kunnen dan de juiste resource bijwerken, zelfs wanneer een klachtenrapport ontvangergegevens afschermt. Amazon SES onderscheidt bijvoorbeeld een succesvolle verzending van bezorging aan de mailserver van de ontvanger en kan events publiceren voor delivery, bounce, complaint, reject, delivery delay, rendering failure, open en click. Verifieer de authenticiteit van webhooks via het gedocumenteerde mechanisme van de provider, valideer het eventschema, dedupliceer op een provider-eventidentifier of deterministische fingerprint en sta herhaalde bezorging van hetzelfde event toe zonder side effects te herhalen. Sla ruwe payloads alleen op indien nodig, versleuteld, met toegangscontrole en beperkte retentie. De genormaliseerde status moet onderscheid maken tussen geaccepteerde, bij de server afgeleverde, gebouncete, met een spamklacht voorziene, vertraagde, geweigerde en op de suppressielijst gezette uitkomsten.

Maak suppressie een controle op het moment van verzenden

Een suppressierecord hoort vóór elke indiening bij de provider gecontroleerd te worden, niet alleen in een dashboard te staan. Adressen met een permanente bounce en klachten vereisen normaal gesproken suppressie; tijdelijke vertragingen in de bezorging vragen om een ander beleid. Bepaal de scope van suppressie bewust. Een lijst voor het hele account kan de gedeelde reputatie beschermen, maar kan ertoe leiden dat de uitkomst bij een ontvanger van de ene tenant een andere tenant blokkeert. Een lijst per tenant vermindert die koppeling, maar heeft nog steeds een laag nodig voor misbruik en platformveiligheid. Leg de reden, het bronevent, de tenant, de aanmaaktijd en een gecontroleerd verwijderpad vast. Het verwijderen van een suppressie na een klacht of permanente bounce heeft gevolgen en moet een bewuste review vereisen, plus bewijs dat het adres geldig is en de ontvanger het bericht verwacht. Kopieer geen ruwe ontvangeradressen naar algemene logs of experimenten; operationele opslag kan het verzendbeleid afdwingen terwijl analytics met geaggregeerde aantallen werkt.

Bescherm batchverzendingen en gevoelige bedrijfsprocessen

Een batch-endpoint vermenigvuldigt de impact van een autorisatie- of validatiefout. Pas dezelfde controles op domeineigendom, suppressie, grootte en inhoud toe op elk item, leg een strikte maximale batchlengte op en geef per item resultaten terug zonder gegevens van een andere tenant te lekken. Rate limits horen te bestaan op het niveau van credential, workspace, domein en provider, met aparte controles voor pieken en voortschrijdend volume. Eén globale limiet op requests per seconde is niet genoeg, want één request kan veel ontvangers bevatten. Vereis in door agents aangestuurde tools een bewuste bevestiging voordat een batch met grote impact wordt ingediend. Scheid rechten voor transactionele en marketingmail als hun regels voor toestemming en operatie verschillen. Monitor ongewone groei in ontvangers, herhaald geweigerde domeinen, grote veranderingen in bounces of klachten en het snel aanmaken van sleutels. Rate limiting draagt bij aan veiligheid, maar vervangt geen authenticatie, objectautorisatie, geverifieerde toestemming of reactie op misbruik.

Test foutpaden vóór productie

Gebruik simulators van de provider of gecontroleerde mailboxen om acceptatie, aflevering bij de ontvangende server, hard bounce, klacht, vertraging, ongeldig domein, ingetrokken sleutel, throttling, provider-timeout, dubbele webhook en herlevering vanuit de wachtrij te testen. Bevestig dat dezelfde idempotentiesleutel één bericht in de applicatie oplevert, dat een opnieuw afgespeeld event geen dubbel neveneffect heeft en dat een tenant niet kan lezen of verzenden met het domein of bericht-ID van een andere tenant. Inspecteer een echt ontvangen bericht op From, Return-Path, DKIM, SPF, DMARC-alignment, weergave van tekst en HTML, afmeldgedrag waar van toepassing, en links. Voer loadtests uit op de wachtrij onder de goedgekeurde providerlimieten en controleer de backpressure in plaats van die te omzeilen. Voeg alarmen toe voor de leeftijd van de wachtrij, uitgeputte retries, fouten bij het verwerken van events, ruimte binnen het quotum, veranderingen in bounces en klachten en ontbrekende callbacks van de provider. Een lanceerchecklist moet voor elke melding en herstelactie een eigenaar noemen.

Pas het patroon zorgvuldig toe met SendHQ

SendHQ biedt bearer-sleutels per workspace, controles voor geverifieerde From-domeinen, het maken van afzonderlijke en batchberichten, inkomende inboxen, berichtevents en suppressieresources. Deze functies ondersteunen de architectuur in deze gids: bewaar de sleutel server-side, maak een berichtresource, bewaar de ID ervan en lees latere events in plaats van de initiële respons als definitieve bezorging te behandelen. Ongeacht het platform blijven aanroepers verantwoordelijk voor bedoelde ontvangers, rechtmatige en verwachte e-mail, juistheid van de inhoud en zorgvuldige goedkeuring van verzendingen met gevolgen.

Veelgestelde vragen

Moet een e-mail-API synchroon verzenden vanuit het webrequest?

Meestal niet. Maak een duurzaam bericht in de applicatie aan en zet het in de wachtrij; laat daarna een worker de provider aanroepen. Zo isoleer je latency, ondersteun je begrensde retries en kun je dubbelzinnige uitkomsten bij de provider makkelijker reconciliëren.

Hoe voorkom ik dubbele e-mails als een request een timeout krijgt?

Gebruik een stabiele job-ID in de applicatie en een idempotentiegrens met een uniciteitsconstraint. Reconcilieer bij een dubbelzinnige timeout eerst de bestaande job voordat je opnieuw iets bij de provider indient met een nieuwe identiteit.

Betekent een geslaagde respons van de e-mail-API dat het bericht is afgeleverd?

Nee. Normaal gesproken geeft het aan dat de API of provider het request heeft geaccepteerd. Gebruik latere events om aflevering bij de ontvangende server, bounce, klacht, vertraging, weigering en suppressie te onderscheiden van de eerste acceptatie.

Welke DNS-records heeft een e-mail-API nodig?

De exacte records hangen af van de provider, maar verzenden in productie vereist meestal domeinverificatie en DKIM, plus een correcte SPF-strategie en een DMARC-beleid dat aligned is met de legitieme verzendstromen.

Mogen API-sleutels in browsercode staan?

Nee. Bewaar workspace- en provider-credentials in server-side opslag voor secrets, sla API-sleutels van de applicatie waar mogelijk gehasht op, toon volledige geheimen één keer en zorg voor snelle mogelijkheden om sleutels in te trekken en te roteren.

Hoe hoort een e-mail-API permanente bounces af te handelen?

Normaliseer het event van de provider, koppel het aan het bericht in de applicatie en zet de ontvanger binnen de bedoelde scope op de suppressielijst voor toekomstige routinematige verzendingen. Verwijderen moet bewust gebeuren en met bewijs worden onderbouwd.

Bronnen