Documentatie

Een fout gevonden?

Je kan deze pagina op GitHub vinden.

Een wijziging voorstellen

Je eerste testmail via de REST API

Met de REST API van SMTPeter kun je e-mails rechtstreeks vanuit je applicatie versturen. In dit artikel verstuur je een eerste testmail, bekijk je de response en controleer je of het bericht is afgeleverd.

Voor je begint

Voordat je een e-mail via de REST API kunt versturen, moet je account klaar zijn voor gebruik. Hiervoor moet je account zijn goedgekeurd na de Vetting, moet het sender domain dat je wilt gebruiken zijn ingesteld en gevalideerd en heb je een access token nodig.

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

Testmail versturen

E-mails verstuur je met een POST request naar het /v1/send endpoint. Je access token geef je mee in de URL. De inhoud van de e-mail stuur je als JSON mee in de body van het request.

Een eenvoudige testmail ziet er bijvoorbeeld zo uit:

POST /v1/send?access_token={JOUW_API_TOKEN}
Host: www.smtpeter.com
Content-Type: application/json

{
    "recipient": "john@doe.com",
    "from": "info@example.com",
    "to": "john@doe.com",
    "subject": "Mijn eerste testmail",
    "text": "Dit is mijn eerste testmail via de SMTPeter REST API."
}

Vervang {JOUW_API_TOKEN} door je eigen access token. Het domein in het from-adres moet overeenkomen met een gevalideerd sender domain in je SMTPeter-account.

Het veld recipient bepaalt naar welk e-mailadres SMTPeter het bericht daadwerkelijk verstuurt. De velden from, to, subject en text worden gebruikt om het e-mailbericht op te bouwen.

Meer mogelijkheden voor het samenstellen van een bericht vind je in MIME data door SMTPeter laten versturen.

Response en message ID

Als SMTPeter het request succesvol accepteert, ontvang je een JSON-object met voor iedere ontvanger een unieke identifier. Bijvoorbeeld:

{
    "a1b2c3d4": "john@doe.com"
}

In dit voorbeeld is a1b2c3d4 de message ID van het verzonden bericht. Wanneer je meerdere ontvangers in één request gebruikt, bevat de response voor iedere ontvanger een eigen message ID.

Deze ID kun je gebruiken om de events van het bericht op te vragen en de aflevering te controleren.

Aflevering controleren

Met de message ID uit de response kun je de geregistreerde events van het bericht opvragen via:

GET /v1/events/messageid/MESSAGEID

Vervang MESSAGEID door de message ID uit de response van het verzendrequest.

Een delivery-event geeft aan dat SMTPeter een aflevering van het bericht heeft geregistreerd. Er kunnen ook andere events voor een bericht beschikbaar zijn, bijvoorbeeld wanneer het bericht niet kon worden afgeleverd.

Meer informatie over de verschillende events en het opvragen daarvan vind je in Opvragen van events.

Als het request mislukt

Wanneer SMTPeter het request niet succesvol kan verwerken, ontvang je een HTTP-statuscode en een beschrijving van de fout. Een succesvol request retourneert een HTTP-statuscode van 200 tot en met 202.

Controleer bij een mislukte request de foutmelding en HTTP-statuscode en pas het request aan op basis van de teruggegeven informatie.

Meer informatie over responses en foutafhandeling vind je in API response.

Meer informatie

Na het versturen van je eerste testmail kun je meer mogelijkheden van de REST API gebruiken: