Je applicatie stuurt gestructureerde data naar een HTTP-endpoint en ontvangt een antwoord met het berichtresultaat of een fout. Dat verzoek en antwoord vormen het werkoppervlak van een e-mail-API.
Wat doet een e-mail-API?
Een verzendendpoint accepteert ontvangers, een onderwerp en tekst- of HTML-inhoud. Het kan ook headers, tags, templates en bijlagen accepteren als de provider ze ondersteunt.
Een event-endpoint of webhook meldt wat er na acceptatie is gebeurd. Veelvoorkomende events zijn aflevering, bounce, klacht, open en klik. Een ontvangende API zet inkomende mail om in gestructureerde berichten voor je applicatie, in plaats van dat je een mailbox moet pollen.
Wat is het verschil tussen een e-mail-API en SMTP?
SMTP vereist dat je applicatie een verbinding opent, authenticeert, commando's stuurt en antwoordcodes leest. Een e-mail-API gebruikt in plaats daarvan HTTP-verzoeken, zodat een clientbibliotheek verbindingshergebruik, JSON-codering, retries en het parsen van antwoorden kan afhandelen.
Kies een API als je applicatie al HTTP gebruikt, gestructureerde events nodig heeft of draait in een omgeving waar het openen van SMTP-verbindingen lastig is. Kies een SMTP-relay als een bestaande mailbibliotheek of mailserver al SMTP spreekt. Beide paden kunnen hetzelfde bericht afleveren.
| Taak | Verzend-API | SMTP-relay | Mailbox-API |
|---|---|---|---|
| Een bericht verzenden | Ja | Ja | Beantwoorden of opstellen |
| Geparsede mail ontvangen | Sommige providers | Nee | Ja |
| Gespreksgeschiedenis lezen | Sommige providers | Nee | Ja |
| Aflevering volgen | Events of webhooks | Antwoordcodes plus events | Berichtstatus en events |
Producten gebruiken de term e-mail-API voor verschillende sets mogelijkheden. Controleer het schema van de provider voordat je aanneemt dat één API elke rij dekt.
Wat moet een API-verzoek bevatten?
Stuur de velden die je provider vereist. Sla de geretourneerde berichtidentifier op. Gebruik een eigen idempotentiesleutel als een retry geen dubbele verzending mag veroorzaken. Valideer ontvangers vóór verzending. Bewaar geheimen op je server.
Een illustratief transactioneel verzoek bevat from, to, subject, text, category: transactional en een idempotentiesleutel die op de server wordt bewaard. Gebruik een geverifieerd verzenddomein voordat je het verstuurt.
Het HTTP-antwoord betekent dat de service het verzoek heeft geaccepteerd. Afleverings-, bounce- en klachtevents komen later, dus een geaccepteerd antwoord bevestigt geen inboxplaatsing.
Gebruik webhooks voor latere events in plaats van een geaccepteerd verzoek te behandelen als bewijs dat een bericht de inbox heeft bereikt. Afleverings- en klachtevents beschrijven wat er na acceptatie is gebeurd.
Hoe verstuur ik met Bird?
Je roept de createEmailMessage API van Bird aan met je werkruimte-API-sleutel, afzender, ontvangers, inhoud en optionele metadata. De handleiding voor e-mailverzending toont de verzoek- en antwoordvelden.
Maak voor antwoorden en inkomende mail een mailbox aan en verwerk de bericht- en afleveringsevents. De handleiding voor mailboxen beschrijft die endpoints en webhooknamen.
Samengevat
- Een e-mail-API stelt verzend- en berichtevents beschikbaar via HTTP.
- Het antwoord bevestigt API-acceptatie, niet inboxplaatsing.
- Idempotentiesleutels maken veilig opnieuw proberen mogelijk.
- Bird biedt verzend- en mailbox-API's met handleidingen voor elk pad.