antispam

diff --git a/README.md b/README.md
index 88d27e30b24be49d8f65a66e3587c26306ccdee1..f776b3cf713c86ad483b85e79b820c013a0985de 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,43 @@
 # antispam
 
-A curated list of common email SPAM measures, domains and scripts to deal with
-it or at least to attempt to potentially identify one.
+A curated list of common email domains, usernames and scripts to deal with it or
+to potentially identify one.
+
+## Data
+
+There is two types of data here, `usernames` and `domains`, both available as a
+plain text file, each item on a new line. Usernames were initially sourced from
+the Big-Blacklist. Domains are a combination of disposable emails and other
+hand-picked items I found as sysadmin of [cirandas.net][cirandas]. 
+
+We also offer some pretty simple awk scripts to process the raw data and spit
+into two flavours: `json` and `yaml`. Generate them on using the `make(1)`
+rules:
+
+```sh
+$ make # will invoke json and yaml
+$ make json
+$ make yaml
+```
+
+## API
 
-We may provision in a near future a tiny API to check if a given domain is known
-as a potential SPAM if that makes sense at all.
+We also offer a pretty barebones API available at [antispam-api][antispam-api].
+Which you can host yourself if you want it. There's a public instance available
+at [antispam.eletrotupi.com][public-instance].
+
+[cirandas]: https://git.eletrotupi.com/cirandas.net
+[antispam-api]: https://git.sr.ht/~porcellis/antispam-api
+[public-instance]: https://antispam.eletrotupi.com
+
+## Contribute
+
+Please do! You can add more items sending a patch to the [mailing list][ml] or
+to me [personally][personal]. If you think your domain was included as a
+mistake, contact me too.
+
+[ml]: mailto:~porcellis/antispam@lists.sr.ht
+[personal]: mailto:porcellis@eletrotupi.com
 
 ## License