Configure e-mail hooks in the PSB

In addition to webhooks, the PSB can send notifications by e-mail. An e-mail hook (also known as a mail hook or mailto hook) sends an e-mail for every event on a chosen topic. This is useful for organisations that do not have their own webhook endpoint, or as a supplement to existing webhooks.

Creating an e-mail hook

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

For every received invoice the PSB now sends a notification e-mail to the specified address. The e-mail address in the action may also contain a placeholder: [senderEmailAddress] or [receiverEmailAddress] to dynamically send to the sender's or recipient's e-mail address.

Note: when using placeholders, always include the fallbackEmail parameter. If the e-mail address is not available in the document, the PSB sends the notification to the fallback address.

Parameters

E-mail hooks support extensive configuration via query parameters in the action URL. You build the URL as mailto:address@domain.com?param1=value&param2=value.

Parameter

Values

Description

includeAttachment

true / false

Attaches the document (XML) to the e-mail

targetDocumentTypeId

URN string

Transforms the attachment to this format before sending (for example from NLCIUS to Factur-X)

filename

template string

File name of the attachment, with placeholders such as {{id}}{{extension}}. URL-encode this value

excludePrimaryAttachment

true / false

Omits the XML attachment (sends only the PDF attachment)

excludeAdditionalAttachments

true / false

Omits additional attachments (embedded PDF/PNG from the XML) (true) or includes them (false)

version

0.9 or 1.0

E-mail template version (see below)

templateId

SendGrid template ID

Use a custom e-mail template (must be configured by eConnect)

fallbackEmail

e-mail address

Required when using placeholders in the address

replyTo

e-mail address

Reply-to address in the e-mail

bcc

comma-separated addresses

BCC recipients

from

e-mail address

Override sender address (only possible with your own ApiKey)

Template versions

The PSB supports two versions of the e-mail template:

Version

Sender address

Explanation

0.9

noreply@everbinding.nl

Legacy template with deprecated sender domain

1.0

noreply@econnect.email

New eConnect template with modern layout

Tip: always use version 1.0 for new configurations. Version 0.9 sends from the old eVerbinding domain, which is no longer actively maintained.

Full example

An e-mail hook that sends an e-mail with the invoice as a PDF attachment (without the XML) for every received invoice:

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

A hook that dynamically sends to the sender, with a fallback:

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

Custom SendGrid template

Want full control over the e-mail layout? Have eConnect configure a custom SendGrid template and use the templateId parameter. You can also link your own SendGrid account by adding an init object with your API key to the hook configuration.

Forwarding incoming invoices to an external mailbox: XML only, no PDF

If a customer forwards incoming invoices to an external mailbox and receives only the XML without the PDF, this is caused by excludeAdditionalAttachments=true. When an e-mail connector/mail hook is created, this parameter is hardcoded to true by default, meaning PDF and other attachments are not sent.

Solution: set the query parameter excludeAdditionalAttachments=false on the mail hook. The additional attachments (PDF/PNG from the XML) will then be included in the e-mail.

Execution: only TechSupport can make this change. If the customer manages the mail hook in the PSB themselves, they can make the change directly.

Multiple recipients

You can specify multiple e-mail addresses by creating separate hooks, or by using the bcc parameter for additional recipients.

Frequently asked questions

Why is fallbackEmail required when using placeholders in the mailto address?

Placeholders such as [senderEmailAddress] or [receiverEmailAddress] are only resolved when that address appears in the document. If it is missing, the PSB sends the notification to the address in fallbackEmail, so you do not lose the message.

What is the difference between template version 0.9 and 1.0?

Version 0.9 uses the older sender domain noreply@everbinding.nl; version 1.0 uses noreply@econnect.email with modern layout. For new configurations, 1.0 is the recommended choice.

How do I send an invoice as an attachment without e-mailing the primary XML?

Set includeAttachment to true and excludePrimaryAttachment to true, so you only send a PDF attachment, for example. Combine this with version=1.0 in the query string for the desired template.

I forward incoming invoices to an external mailbox but only receive the XML, not the PDF. What is the cause?

This is caused by excludeAdditionalAttachments=true on the mail hook. When an e-mail connector is created, this parameter is hardcoded to true, meaning PDF and other attachments from the XML are not included. Set excludeAdditionalAttachments=false to include the additional attachments. Contact TechSupport if you do not manage the mail hook in the PSB yourself.

See the full API specification at psb.econnect.eu for all available configurations and examples.

Open the API reference