E-mail hooks configureren in de PSB

Naast webhooks biedt de PSB de mogelijkheid om notificaties per e-mail te versturen. Een e-mail hook (ook wel mailhook of mailto-hook) stuurt een e-mail bij elke gebeurtenis op een gekozen topic. Handig voor organisaties die geen eigen webhook-endpoint hebben, of als aanvulling op bestaande webhooks.

Een e-mail hook aanmaken

Registreer een hook via de API met een mailto:-action:

{
  "action": "mailto:finance@jouw-bedrijf.nl",
  "topics": ["InvoiceReceived"]
}

Bij elke ontvangen factuur stuurt de PSB nu een notificatie-e-mail naar het opgegeven adres. Het e-mailadres in de action mag ook een placeholder bevatten: [senderEmailAddress] of [receiverEmailAddress] om dynamisch naar het e-mailadres van de afzender of ontvanger te sturen.

Let op: Gebruik bij placeholders altijd de fallbackEmail-parameter. Als het e-mailadres niet beschikbaar is in het document, stuurt de PSB de notificatie naar het fallback-adres.

Parameters

E-mail hooks ondersteunen uitgebreide configuratie via queryparameters in de action-URL. Je bouwt de URL op als mailto:adres@domein.nl?param1=waarde&param2=waarde.

Parameter

Waarden

Beschrijving

includeAttachment

true / false

Voegt het document (XML) als bijlage toe aan de e-mail

targetDocumentTypeId

URN-string

Transformeert de bijlage naar dit formaat voor verzending (bijvoorbeeld van NLCIUS naar Factur-X)

filename

templatestring

Bestandsnaam van de bijlage, met placeholders zoals {{id}}{{extension}}. URL-encode deze waarde

excludePrimaryAttachment

true / false

Laat de XML-bijlage weg (stuur alleen de PDF-bijlage mee)

excludeAdditionalAttachments

true / false

Additionele bijlagen (ingebedde PDF/PNG uit de XML) weglaten (true) of meesturen (false)

version

0.9 of 1.0

E-mailtemplateversie (zie hieronder)

templateId

SendGrid template ID

Gebruik een eigen e-mailtemplate (moet door eConnect zijn geconfigureerd)

fallbackEmail

e-mailadres

Verplicht bij gebruik van placeholders in het adres

replyTo

e-mailadres

Reply-to-adres in de e-mail

bcc

komma-gescheiden adressen

BCC-ontvangers

from

e-mailadres

Afzenderadres overschrijven (alleen mogelijk met eigen ApiKey)

Templateversies

De PSB ondersteunt twee versies van het e-mailtemplate:

Versie

Afzenderadres

Toelichting

0.9

noreply@everbinding.nl

Oud template met verouderd afzenderdomein

1.0

noreply@econnect.email

Nieuw eConnect-template met moderne opmaak

Tip: Gebruik altijd versie 1.0 voor nieuwe configuraties. Versie 0.9 stuurt vanuit het oude eVerbinding-domein, dat niet meer actief wordt onderhouden.

Volledig voorbeeld

Een e-mail hook die bij elke ontvangen factuur een e-mail stuurt met de factuur als PDF-bijlage, zonder de XML:

mailto:finance@jouw-bedrijf.nl?includeAttachment=true&excludePrimaryAttachment=true&version=1.0

Een hook die dynamisch naar de afzender stuurt, met een fallback:

mailto:[senderEmailAddress]?includeAttachment=true&version=1.0&fallbackEmail=backup@jouw-bedrijf.nl

Eigen SendGrid-template

Wil je volledige controle over de opmaak van de e-mail? Laat door eConnect een eigen SendGrid-template configureren en gebruik de templateId-parameter. Je kunt ook een eigen SendGrid-account koppelen door een init-object met je API-key toe te voegen aan de hook-configuratie.

Inkomende factuur doorsturen naar externe mailbox: alleen XML, geen PDF

Ondervindt een klant dat doorgestuurde inkomende facturen alleen de XML bevatten en niet de PDF, dan wordt dit veroorzaakt door excludeAdditionalAttachments=true. Bij het aanmaken van een e-mailconnector/mailhook staat deze parameter standaard op true, waardoor PDF/bijlagen niet worden meegestuurd.

Oplossing: stel excludeAdditionalAttachments=false in op de mailhook. De additionele bijlagen (PDF/PNG uit de XML) worden dan wél in de e-mail meegestuurd.

Uitvoering: gaat het om de automatisch aangemaakte e-mailconnector (Collabrr-platform), dan kan alleen TechSupport deze aanpassing doorvoeren. Wijzig de connector na de fix niet zelf: een handmatige aanpassing overschrijft de correctie en onderdrukt de PDF-bijlage opnieuw. Beheert de klant een eigen PSB-mailhook zelf, dan kan de klant de parameter zelf op false zetten.

Meerdere ontvangers

Je kunt meerdere e-mailadressen opgeven door aparte hooks aan te maken, of door gebruik te maken van de bcc-parameter voor aanvullende ontvangers.

Undeliverable/NDR op een no-reply-adres is geen Peppol-fout

Een e-mail hook stuurt notificaties vanaf een no-reply-adres (noreply@everbinding.nl voor versie 0.9, noreply@econnect.email voor versie 1.0). Antwoordt de ontvangende mailbox hierop, bijvoorbeeld via een automatische out-of-office of afwezigheidsassistent, dan bounced dat antwoord vaak terug met een Undeliverable- of NDR-melding (non-delivery report), meestal met foutcode 550 5.1.10 Recipient not found.

Ontvang je zo'n Undeliverable/NDR met een onderwerp dat verwijst naar een PSB-notificatie zoals InvoiceSent, dan betekent dat niet dat de factuur niet is afgeleverd via Peppol. Het topic InvoiceSent betekent juist dat de uitgaande factuur succesvol is afgeleverd bij de ontvangende partij (zie webhooks instellen: veelgebruikte topics). De bounce ontstaat omdat de mailbox van de klant automatisch antwoordde op een no-reply-adres, niet omdat er een Peppol-afleverfout is.

Controleren:

Lees de bijlage van de NDR: staat het oorspronkelijke onderwerp of de envelope-afzender op een no-reply-adres (noreply@everbinding.nl of noreply@econnect.email)?
Gaat het om een notificatie zoals InvoiceSent, dan is de factuur al succesvol afgeleverd. De bounce is een reactie op de notificatiemail zelf, geen afleverfout.
Vraag de klant om de auto-reply of afwezigheidsassistent uit te zetten voor mail van everbinding.nl en econnect.eu, of no-reply-adressen uit te sluiten van automatische antwoorden.

Een eigen platform-afleverfout herken je aan de status Delivery Failed in Postvak Uit, niet aan een NDR op een no-reply-adres.

Veelgestelde vragen

Waarom is fallbackEmail verplicht bij placeholders in het mailto-adres?

Placeholders zoals [senderEmailAddress] of [receiverEmailAddress] vullen alleen als het adres in het document staat. Ontbreekt dat, dan stuurt de PSB de notificatie naar het adres in fallbackEmail, zodat je geen bericht kwijtraakt.

Wat is het verschil tussen templateversie 0.9 en 1.0?

Versie 0.9 gebruikt het oudere afzenderdomein noreply@everbinding.nl; versie 1.0 gebruikt noreply@econnect.email met moderne opmaak. Voor nieuwe configuraties is 1.0 de aanbevolen keuze.

Hoe stuur ik een factuur als bijlage zonder de primaire XML mee te e-mailen?

Zet includeAttachment op true en excludePrimaryAttachment op true, zodat je bijvoorbeeld alleen een PDF-bijlage meestuurt. Combineer dit met version=1.0 in de querystring voor het gewenste template.

Ik stuur inkomende facturen door naar een externe mailbox, maar ontvang alleen de XML en niet de PDF. Wat is de oorzaak?

Dit wordt veroorzaakt door excludeAdditionalAttachments=true op de mailhook. Bij het aanmaken van een e-mailconnector staat deze parameter hardcoded op true, waardoor PDF/bijlagen uit de XML niet worden meegestuurd. Stel excludeAdditionalAttachments=false in om de additionele bijlagen wél mee te sturen. Neem contact op met TechSupport als je de mailhook niet zelf beheert in de PSB; wijzig de automatisch aangemaakte connector na een TechSupport-fix niet zelf, want dat overschrijft de correctie.

Ik krijg een Undeliverable/NDR terug op een InvoiceSent-notificatie. Betekent dat een mislukte Peppol-aflevering?

Nee. Het topic InvoiceSent betekent dat de factuur al succesvol is afgeleverd bij de ontvangende partij. Een Undeliverable of NDR op zo'n notificatiemail ontstaat doordat de mailbox van de ontvanger automatisch antwoordde (bijvoorbeeld een out-of-office) op het no-reply-afzenderadres van de notificatie (noreply@everbinding.nl of noreply@econnect.email), niet doordat de factuur niet is aangekomen. Controleer bij twijfel of het antwoord echt een reactie is op no-reply, en vraag de auto-reply voor die domeinen uit te zetten.

Bekijk de volledige API-specificatie op psb.econnect.eu voor alle mogelijke configuraties en voorbeelden.

Open de API-referentie