Documentatie

Je eerste testmail via de REST API

In dit artikel verstuur je een testmail via de REST API van SMTPeter. Je controleert eerst of SMTPeter het request accepteert en daarna of het bericht bij de ontvangende mailserver is afgeleverd.

Voor je begint

Voordat je een testmail kunt versturen, heb je een goedgekeurd SMTPeter-account, een gevalideerd Senderdomain en een API-access-token nodig.

SMTPeter gebruikt je Senderdomain om namens jouw domein e-mails te versturen.

Heb je deze stappen nog niet doorlopen? Volg dan eerst Direct aan de slag en REST API configureren.

Testmail versturen

Je verstuurt een POST-request naar /v1/send, met je API-access-token in de URL en de e-mailgegevens als JSON in de body.

Met het volgende cURL-voorbeeld verstuur je een testmail vanuit een terminal die Bash of zsh ondersteunt:

curl --include --request POST \
  "https://www.smtpeter.com/v1/send?access_token=YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": "ontvanger@example.net",
    "from": "info@example.com",
    "to": "ontvanger@example.net",
    "subject": "Mijn eerste testmail",
    "text": "Dit is mijn eerste testmail via de SMTPeter REST API."
  }'

Voordat je het request uitvoert, vervang je de volgende waarden:

  • YOUR_API_TOKEN door je eigen API-access-token.
  • info@example.com door een afzenderadres van een gevalideerd Senderdomain in je SMTPeter-account.
  • ontvanger@example.net door een e-mailadres waarop je de testmail wilt ontvangen.

Dit voorbeeld gebruikt cURL en een JSON-request met een tekstbericht. Je kunt de REST API ook vanuit andere programmeertalen gebruiken en berichten op andere manieren samenstellen.

Let op: je API-access-token geeft toegang tot je SMTPeter-account. Voorkom dat URL's met je token in logbestanden of openbare repositories terechtkomen. Meer informatie vind je in REST API configureren.

De belangrijkste velden

Het voorbeeld gebruikt vijf velden:

  • recipient: het e-mailadres waarnaar SMTPeter het bericht verstuurt.
  • from: het afzenderadres dat in de e-mail wordt weergegeven.
  • to: het ontvangstadres dat zichtbaar is in de e-mail.
  • subject: het onderwerp van de e-mail.
  • text: de tekstinhoud van de e-mail.

recipient bepaalt het afleveradres. to bepaalt welk ontvangstadres in de e-mailheader staat. Deze adressen hoeven niet gelijk te zijn.

Voor deze test gebruik je in beide velden hetzelfde adres. Zo komt het afleveradres overeen met het adres dat in de e-mail zichtbaar is.

SMTPeter stelt op basis van deze velden automatisch het MIME-bericht samen. Meer mogelijkheden vind je in MIME door SMTPeter laten maken.

Response en message ID

Als SMTPeter het verzendrequest accepteert, ontvang je een HTTP-statuscode van 200 tot en met 202 en een JSON-object met een unieke message ID per ontvanger.

Door --include in het cURL-voorbeeld zie je zowel de HTTP-headers, waaronder de statuscode, als de JSON-body.

Een voorbeeld van de JSON-response:

{
  "a1b2c3d4": "ontvanger@example.net"
}

In dit voorbeeld is a1b2c3d4 de message ID en ontvanger@example.net het bijbehorende ontvangstadres.

Wanneer je meerdere ontvangers in één request opgeeft, ontvang je voor iedere ontvanger een afzonderlijke message ID.

Bewaar de message ID uit je eigen response. Je gebruikt deze om de events van het bericht op te vragen. a1b2c3d4 is alleen een voorbeeld-ID.

Let op: een succesvolle API-response bevestigt dat SMTPeter het request heeft geaccepteerd. Dit betekent nog niet dat het bericht bij de ontvangende mailserver is afgeleverd.

Aflevering controleren

Met de message ID vraag je de geregistreerde events van het bericht op.

Hiervoor gebruik je een GET-request naar /v1/events/messageid/MESSAGEID.

Je kunt de events bijvoorbeeld opvragen met cURL:

curl --request GET \
  "https://www.smtpeter.com/v1/events/messageid/a1b2c3d4?access_token=YOUR_API_TOKEN"

Vervang a1b2c3d4 door de message ID uit je eigen response en YOUR_API_TOKEN door je API-access-token.

SMTPeter geeft een JSON-array terug met de events van het bericht.

Een vereenvoudigd voorbeeld van een response met een delivery-event:

[
  {
    "event": "delivery",
    "data": {
      "id": "a1b2c3d4"
    }
  }
]

Het veld event geeft het type gebeurtenis aan. Het veld data bevat aanvullende informatie over die gebeurtenis. Welke gegevens beschikbaar zijn, hangt af van het eventtype.

Enkele relevante events zijn:

  • delivery: SMTPeter heeft het bericht aan de ontvangende mailserver overgedragen.
  • failure: de aflevering van het bericht is mislukt.
  • bounce: SMTPeter heeft een terugmelding op het bericht ontvangen.

Bij een bounce controleer je de inhoud van de terugmelding. Dit kan een melding over een mislukte aflevering zijn, maar ook een ander automatisch gegenereerd bericht.

Als er nog geen delivery-event is

De aflevering kan langer duren dan het verwerken van je API-request.

Zie je nog geen delivery-event? Dan kan het bericht nog in behandeling zijn. Je kunt de events na een korte wachttijd opnieuw opvragen met dezelfde message ID.

Je hoeft het bericht hiervoor niet opnieuw te versturen.

Een delivery-event bevestigt bovendien niet dat het bericht in de inbox van de ontvanger is terechtgekomen. De ontvangende mailserver kan het bericht bijvoorbeeld nog als spam classificeren of later een foutmelding terugsturen.

Ook na een delivery-event kunnen dus nog andere events verschijnen.

Standaard krijg je bij het opvragen op basis van een message ID de events tot een maand na verzending. Met de parameters start en end kun je events uit een andere periode opvragen.

Meer informatie vind je in Opvragen van events.

Als het request mislukt

Wanneer SMTPeter een API-request niet kan verwerken, ontvang je een HTTP-foutcode en een beschrijving van het probleem.

In de foutmelding lees je waarom SMTPeter het request niet kon verwerken. Controleer bijvoorbeeld of je API-access-token geldig is en of de vereiste gegevens aanwezig zijn.

Meer informatie over HTTP-statuscodes en foutafhandeling vind je in API respons.

Voorkom dubbele verzendingen

Bij een timeout ontvang je mogelijk geen response, terwijl SMTPeter het oorspronkelijke verzendrequest al heeft geaccepteerd.

Verstuur hetzelfde bericht daarom niet automatisch opnieuw zonder te controleren of het eerdere request is verwerkt. Anders kan de ontvanger dezelfde e-mail meerdere keren ontvangen.

Dit is ook belangrijk wanneer je het voorbeeld in een applicatie gebruikt. Herhaalde triggers of identieke verzendrequests kunnen meerdere e-mails veroorzaken. Houd daarom bij welke berichten al zijn aangeboden en voorkom dat dezelfde verzendopdracht onbedoeld opnieuw wordt uitgevoerd.

Controleert je applicatie automatisch de aflevering? Gebruik dan een wachttijd tussen eventrequests en voorkom dat je hetzelfde endpoint onnodig vaak aanroept.

Meer informatie

Je kunt de REST API ook gebruiken voor: