Problemen oplossen met transactionele e-mail

Dit artikel behandelt de meest voorkomende problemen met transactionele e-mail van Flexmail — authenticatiefouten, bezorgbaarheidsproblemen en API- of SMTP-storingen — en wat je eraan kunt doen.

Authenticatie- en installatiefouten

API geeft een 401 Unauthorized-fout

Je account-ID of personal access token is onjuist. Controleer beide zorgvuldig:

• De gebruikersnaam is je numerieke account-ID, niet je e-mailadres.
• Het wachtwoord is een personal access token aangemaakt via Instellingen → API → Personal acces tokens, niet je Flexmail-inlogwachtwoord.
• Zorg ervoor dat het token volledig is gekopieerd, zonder spaties of regeleinden aan het einde.
• Maak bij twijfel een nieuw token aan en probeer het opnieuw.

SMTP-verbinding mislukt of time-out

Controleer het volgende:

• Je gebruikt host submission.flexmail.eu, poort 587, met STARTTLS.

• Je server of hostingomgeving staat uitgaande verbindingen op poort 587 toe.

  Sommige shared-hostingproviders blokkeren deze poort — neem contact op met je host om dit te bevestigen.

• Je SMTP-inloggegevens zijn de gebruikersnaam en het wachtwoord die Flexmail heeft verstrekt bij het activeren van je SMTP-toegang. Dit zijn aparte gegevens van je account-ID en personal access token, die alleen voor de HTTP API worden gebruikt.
• Je verzendadres is geverifieerd in Flexmail.

Verzendadres niet geverifieerd

Als je probeert te verzenden van een adres dat niet is geverifieerd in Flexmail, wordt de verzending geweigerd. Ga naar Instellingen → Afzenders toevoegen of verwijderen, voeg het adres toe en klik op de verificatielink in de e-mail die Flexmail stuurt.

Bezorgbaarheidsproblemen

E-mails komen in de spam terecht

Spamplaatsing bij transactionele e-mail wordt vrijwel altijd veroorzaakt door een van de volgende drie zaken:

• E-mailauthenticatie is niet geconfigureerd of onjuist. Controleer of SPF-, DKIM- en DMARC-records aanwezig zijn voor je verzendende domein. Zelfs één ontbrekend of verkeerd geconfigureerd record kan spamplaatsing veroorzaken. Configuratie-instructies zijn te vinden in de API-documentatie op email-api.flexmail.eu/documentation onder E-mailauthenticatie.
• Afzendersreputatie is laag. Als je domein of IP een geschiedenis heeft van spamklachten of hoge bouncepercentages — van welk verzendplatform dan ook, niet alleen Flexmail — kunnen inboxproviders je e-mail naar spam sturen. Zie "Afzendersreputatie begrijpen" voor informatie over het beoordelen en verbeteren van reputatie.
• Inhoud activeert spamfilters. Bepaalde onderwerppatronen, buitensporig veel links of afbeeldingszware e-mails met weinig tekst kunnen spamfilters activeren. Test je transactionele e-mails met een tool zoals Mail-Tester (mail-tester.com) om inhoudsgerelateerde problemen te identificeren.

E-mails komen helemaal niet aan

Als de API een succesbericht teruggeeft maar de e-mail niet aankomt:

• Controleer je webhook-events (indien geconfigureerd) — een bounce-event kort na verzending duidt op een bezorgingsfout.
• Controleer of het ontvangersadres bestaat en correct is gespeld.
• Vraag de ontvanger om zijn spammap te controleren.
• Controleer of het domein van de ontvanger een strikt DMARC-beleid heeft — zonder correct geconfigureerd DKIM kunnen je e-mails stilzwijgend worden geweigerd.
• Sommige zakelijke e-mailsystemen weigeren e-mail van nieuwe of laag-reputatie-afzenders. Probeer te verzenden naar een persoonlijk Gmail- of Outlook-adres om filtering aan de ontvangerskant uit te sluiten.

Hoog bouncepercentage

Een hoog bouncepercentage bij transactionele e-mail betekent doorgaans dat je verzendt naar adressen die niet bestaan of niet meer actief zijn. Controleer je adresverzamelingsproces:

• Valideer je het formaat van e-mailadressen op het moment van invoer?
• Stuur je een bevestigings- of verificatie-e-mail voordat je een nieuw adres vertrouwt?
• Verwijder je hard-gebounced adressen snel uit je systeem?

API- en integratiefouten

API geeft een 422- of 400-fout

Deze fouten duiden op een probleem met je verzoek: een ontbrekend verplicht veld, een ongeldige parameterwaarde of een verkeerd opgemaakte verzoekbody. Controleer de foutmelding in de responsbody voor details. De API-documentatie op email-api.flexmail.eu/documentation bevat een overzicht van alle verplichte en optionele parameters voor elk endpoint.

API geeft een 429 Too Many Requests-fout

Je hebt een snelheidslimiet bereikt. De API-documentatie beschrijft de snelheidslimieten voor je abonnementstype. Voeg retry-logica met exponentiële backoff toe aan je integratie om hier soepel mee om te gaan.

Template-variabelen worden niet vervangen

Als plaatshouders letterlijk verschijnen in de bezorgde e-mail:

• Controleer of je de variabele waarden correct meegeeft in het API-verzoek. Zie de sectie Templates in de API-documentatie voor de exacte parameterstructuur.
• Controleer of de plaatshouder-syntaxis in je template exact overeenkomt met wat de API verwacht.
• Zorg ervoor dat je het juiste template-ID in je API-aanroep gebruikt.

Webhooks komen niet aan

Als je webhook-endpoint geen events ontvangt:

• Bevestig dat je endpoint publiekelijk toegankelijk is via HTTPS.
• Controleer of je endpoint snel een 2xx-respons teruggeeft — een traag of niet-reagerend endpoint zal Flexmail doen denken dat de bezorging is mislukt.
• Controleer je serverlogboeken op inkomende POST-verzoeken om een routerings- of firewallprobleem uit te sluiten.
• Verifieer of je webhook-endpoint-URL correct is geregistreerd in de API.

Hulp krijgen

Als je het bovenstaande hebt doorlopen en het probleem aanhoudt, neem dan contact op met het Flexmail-ondersteuningsteam via api@flexmail.be. Voeg het volgende toe aan je bericht om de diagnose te versnellen:

• Het bericht-ID van een mislukte verzending (uit de API-respons of je logboeken).
• Het e-mailadres van de ontvanger waarmee je hebt getest.
• De foutmelding of responsbody van de API, indien van toepassing.
• Het resultaat van een e-mailauthenticatiecontroletool zoals MXToolbox of Mail-Tester.

Volgende stappen

• Zie "Aan de slag met de transactionele API" voor de juiste installatievolgorde.
• Zie "Afzendersreputatie begrijpen" voor informatie over het beoordelen en beschermen van je verzendreputatie.
• Bekijk de API-documentatie op email-api.flexmail.eu/documentation voor foutcodes en snelheidslimietdetails.