Email Subscription Guide

This is a walk-trough on how to create an integration to our WebSub subscription service (hub.mfn.se) for email subscriptions.

For our subscription mechanism, we use WebSub for subscribing to HTTP post hooks. We've generalized it and have created an extended subscription flow for FTP, SFTP, and SMTP in addition to HTTP.

Therefore our form data parameters have got the same specification, such as hub.callback, hub.mode or hub.topic.

In order for you to get a sense of how it works, here is an example of a POST request:

PRODUCTION POST URL: https://hub.mfn.se

STAGING POST URL: https://hub.mfn.modfin.se

Form data
"hub.mode": "subscribe"
"hub.callback": "smtp://[e-mail]" 'smtp://' is important, since the same POST URL can be used, WebSub HTTP, FTP subscriptions etc. The e-mail to the person subscribing.
"hub.topic": [The WebSub topic URL to subscribe to] Explained further below
"from_widget": "true" Lets backend know its coming from a subscription widget, which makes the verification mail better for this purpose, with company logo etc
"lang": "sv" Language of verification mail to send to the callback email address. Requires from_widget=true and topic to define an .author.entity_id

"from_widget" and"lang" is not part of the WebSub standard and are not required, but should be included for email subscriptions for optimally formatted subscription verification mails.

TOPIC URL

The topic URLhub.topic is what decides what to subscribe to, and it's the most complicated part.

It should have this form to subscribe to everything from an entity ID:

/a?type=all&.author.entity_id={ENTITY ID}

Topic should also be URL encoded.

And optionally, it can include a filter to further screen out specific types of press releases:

/a?type=all&.author.entity_id={ENTITY ID}&filter={FILTER}

Where filter is a kind of filter DSL expression for matching press releases which are MFN specific, and has a LISP style syntax.

Six different examples examples of filter expressions

1. Matches all reports

(.properties.tags@>["sub:report"])

The ".properties.tags" property of the press release should include the tag "sub:report" (which means it's a report)

2. Matches reports or PR releases

(or (.properties.tags@>["sub:report"]) (.properties.type="pr"))

3. Matches reports and PR releases

(and (.properties.tags@>["sub:report"]) (.properties.type="pr"))

(NOTE: this will not match anything, since it's not possible for a report to be of type PR)

4. Matches regulatory press releases

(.properties.tags@>[":regulatory"])

5. Matches all reports that are not written in Swedish

(and (.properties.tags@>["sub:report"]) (not (.properties.lang="sv")))

6. Matches all releases where the subject are other companies, common for analysis companies

(or (.subjects[].entity_id @> ["{ENTITY ID 1}"]) (.subjects[].entity_id @> ["{ENTITY ID 2}"]))

To see which subjects a company can write about, excluding itself, check: https://editor.mfn.se/api/deskman/public/customer/by-entity/{ENTITY ID}/subjects

Finally: Building a complete topic URL

Now that we have gathered ENTITY_ID and and FILTER we can construct the final topic URL that should be submitted as hub.topic

Here's an example that subscribes to all reports of a specific entity id:

/a?type=all&.author.entity_id=2c07a2db-2f22-4a67-ab46-ccb464296638&filter=(.properties.tags@>["sub:report"])

Do note that the topic URL must be FORM encoded (x-www-form-urlencoded) since its submitted as part of the Form data.