Na het afrekenen heeft je applicatie een bestelling en een ontvanger die een bon nodig heeft. Ze gebruikt een e-mail-API om het bericht in te dienen. Ze slaat het antwoord op bij de bestelling.
Indiening is alleen de eerste stap. Je applicatie heeft ook een manier nodig om een verzoek opnieuw te proberen. Ze moet weten wat er na indiening met het bericht is gebeurd.
Hoe wordt een applicatiegebeurtenis een e-mail?
Je applicatie zet een voltooide transactie of een accountverzoek om in een verzendoperatie. De e-mailservice handelt de aflevering af na indiening.
Voor een bon is die volgorde:
- Je applicatie bevestigt dat de bestelling klaar is voor een bon.
- Ze selecteert de ontvanger en levert de bestelgegevens aan als inhoud of templatewaarden.
- Ze dient de verzending in en slaat het geretourneerde bericht-ID op bij de bestelling.
- Ze werkt het verzendrecord bij wanneer aflevergebeurtenissen binnenkomen.
Een e-mail-API kan zowel transactionele als marketingberichten ondersteunen. Het gebruik van een API maakt promotionele inhoud niet transactioneel en heft CAN-SPAM-verplichtingen niet op.
Wat betekent een succesvol antwoord?
Een succesvol indieningsantwoord legt vast wat de service heeft geaccepteerd. Het staat los van de latere beslissing van de ontvangende mailserver.
De 202-status van HTTP betekent dat een verzoek is geaccepteerd voor verwerking. De verwerking is niet afgerond, dus dat antwoord kan geen aflevering vaststellen.
Het exacte antwoord hangt af van de API. Het verzendendpoint van Bird retourneert bijvoorbeeld een bericht in de wachtrij met een id. Bewaar dat ID bij de bestelling of accountgebeurtenis zodat latere resultaten aan het oorspronkelijke verzoek gekoppeld kunnen worden.
Als validatie mislukt, retourneert Bird 422 met een foutmelding die uitlegt waarom het verzoek is afgewezen.
Hoe voorkomen retries dubbele berichten?
Een idempotentiesleutel identificeert één logische verzendoperatie over retries heen. Een API die dit ondersteunt, kan een herhaald verzoek herkennen in plaats van een nieuwe verzending aan te maken.
Een bon voor bestelling 8472 kan bijvoorbeeld de sleutel receipt/order-8472 gebruiken. Probeer hetzelfde verzoek opnieuw met die sleutel als de verbinding wegvalt voordat je het antwoord ontvangt.
Een nieuwe sleutel identificeert een andere operatie. Je applicatie moet de oorspronkelijke sleutel daarom bewaren over eigen retries en herstarts heen.
Idempotentie heeft een bewaarvenster dat door de provider wordt bepaald. Zodra dat venster verloopt, kan dezelfde sleutel als een nieuw verzoek worden verwerkt.
Hoe rapporteren webhooks aflevering?
Een webhook stuurt een gebeurtenis naar je applicatie wanneer de status van het bericht verandert. Hiermee kan je applicatie haar records bijwerken na het initiële antwoord van de API.
De e-mailgebeurtenissen van Bird onderscheiden deze uitkomsten:
| Gebeurtenis | Wat het vaststelt |
|---|---|
email.delivered | De ontvangende mailserver heeft de verantwoordelijkheid voor het bericht geaccepteerd |
email.deferred | Een tijdelijke afleverfout wordt opnieuw geprobeerd |
email.bounced | De ontvangende server heeft aflevering geweigerd |
email.rejected | Het bericht heeft geen afleverpoging bereikt |
Acceptatie door de server stelt geen inbox-plaatsing of lezing vast. Een ontvangende server kan ook een latere bounce rapporteren na acceptatie van het bericht.
Je webhookhandler moet de handtekening van de afzender verifiëren en dubbele afleveringen afhandelen. Het webhookcontract van Bird vereist deduplicatie met webhook-id.
Wat veranderen templates?
Een opgeslagen template scheidt herbruikbare berichtinhoud van de waarden die per verzending worden meegegeven. Je applicatie kan een bestelnummer en klantnaam meegeven zonder de volledige e-mailbody samen te stellen.
Met de templates van Bird verwijst een verzending naar een gepubliceerd template en levert de parameters aan. Het template bevat het onderwerp en de body.
Een template beslist niet wanneer een bestelling voltooid is of een wachtwoordreset geautoriseerd is. Die beslissingen blijven in je applicatie.
Wat is het verschil met SMTP-relay of een marketingplatform?
Een HTTP API en een SMTP-relay zijn verschillende indieningsinterfaces. Een marketingplatform beheert ook campagnewerk, zoals het selecteren van een doelgroep en het inplannen van een verzending.
| Interface of product | Wat je applicatie aanlevert |
|---|---|
| E-mail-API | Een gestructureerd HTTP-verzoek met ontvangers en inhoud of een template |
| SMTP-relay | Een SMTP-conversatie die ontvangers en een opgemaakt e-mailbericht indient |
| Marketingplatform | Campagne-inhoud, doelgroepselectie en verzendinstructies |
SMTP definieert de uitwisseling voor het indienen van een bericht en de ontvangers. Het kan transactionele of marketingmail vervoeren.
De SMTP-relay van Bird en HTTP API gebruiken hetzelfde afleverproduct, inclusief gebeurtenissen en suppressieafhandeling. Het kiezen van SMTP verwijdert die mogelijkheden niet.
Hoe verstuur je transactionele e-mail via Bird?
Je roept POST /v1/email/messages aan met een geverifieerde afzender, ontvangers en inline-inhoud of een gepubliceerd template. Stel category: "transactional" in voor operationele mail. Het antwoord is 202 Accepted met een bericht-ID; aflevering verloopt asynchroon.
Gebruik een Idempotency-Key voor elke logische verzending. Bird bewaart een voltooid antwoord drie uur. Een retry na dat venster kan een nieuw bericht aanmaken, dus houd zelf een record bij van voltooide zakelijke gebeurtenissen.
Abonneer je op e-mailgebeurtenissen en koppel email_id en recipient_id aan je records. Een bericht met meerdere ontvangers heeft afzonderlijke uitkomsten per ontvanger.
Voor providerselectie behandelt de checklist voor transactionele e-mailservices de aflever- en operationele mogelijkheden om te vergelijken.