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:[email protected]",
  "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:[email protected]?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)

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

[email protected]

Legacy template with deprecated sender domain

1.0

[email protected]

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:[email protected]?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&[email protected]

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.

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 [email protected]; version 1.0 uses [email protected] 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.

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

Open the API reference