> For the complete documentation index, see [llms.txt](https://modfin.gitbook.io/mfn-integration-guide/-MbDBLBpI3LuyvwyWLVw/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://modfin.gitbook.io/mfn-integration-guide/-MbDBLBpI3LuyvwyWLVw/api/email-subscription-guide.md).

# Email Subscription Guide

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"`**                                                                                                                                                                                                                                     |
| <p><strong><code>"hub.callback": "smtp\://subscription\_<email@placeholder.se>"</code></strong></p><p>  <em>'smtp\://' is important, since the same POST URL can be used, WebSub HTTP, FTP subscriptions etc. The e-mail to the person subscribing.</em> </p>     |
| <p><strong><code>"hub.topic": \[The WebSub topic URL to subscribe to]</code></strong></p><p>  <em>Explained further below</em></p>                                                                                                                                |
| <p><strong><code>"from\_widget": "true"</code></strong></p><p>  <em>Lets backend know its coming from a subscription widget, which makes</em></p><p>  <em>the verification mail better for this purpose, with company logo etc</em></p>                           |
| <p><strong><code>"lang": "sv"</code></strong></p><p>  <em>Language of verification mail to send to the callback email address.  Requires</em> <strong><code>from\_widget=true</code></strong> <em>and topic to define an</em> <code>.author.entity\_id</code></p> |

{% hint style="info" %}
`"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.
{% endhint %}

#### TOPIC URL

The topic URL`hub.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.&#x20;

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**&#x20;

`(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.*