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: alleen TechSupport kan deze aanpassing doorvoeren. Beheert de klant de mailhook zelf in de PSB, dan kan de klant de wijziging zelf doorvoeren.

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.

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.

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

Open de API-referentie