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:
POST URL: https://hub.mfn.se
Form data |
|
'smtp://' is important, since the same POST URL can be used, WebSub HTTP, FTP subscriptions etc. The e-mail to the person subscribing. |
explained further below |
lets backend know its coming from a subscription widget, which makes the verification mail better for this purpose, with company logo etc |
language of verification mail to send to the callback email address. |
"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}
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.
Five 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")))
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.
Last updated