Guide

Apprise - come inviare notifiche verso qualsiasi servizio di messaggistica

Scopri Apprise, lo strumento che unifica tutte le tue notifiche. Invia messaggi a email, Telegram, Slack e decine di altri servizi con una singola chiamata API. Semplifica i tuoi script, risparmia tempo e centralizza la gestione degli avvisi in un unico posto.

Se siete come me, vi è capitato almeno una volta di trovarvi in una di queste situazioni:

State scrivendo uno script in PowerShell o in Python ed avete bisogno che questo invii una email, ma implementare questa funzionalità richiede più righe di codice di quelle della funzione principale dello script.
Volete integrare il supporto all'invio di notifiche tramite Telegram ma non avete intenzione di installare le librerie necessarie e studiare la documentazione ufficiale per farlo.
Dovete far sì che un programma invii una mail al vostro responsabile, un messaggio sul canale Slack del vostro reparto e -perché no- una notifica sul vostro cellulare ma implementare tre funzionalità diverse vi porterebbe via troppo tempo.

E se vi dicessi che esiste un software open-source che, esponendo un endpoint API semplicissimo, vi permette di fare tutto questo aggiungendo una singola riga di codice, senza installare dipendenze, e che si integra con una miriade di servizi di messaggistica?

Sto parlando di Apprise, la manna dal cielo che vi risparmierà ore di studio, centinaia di righe di codice, e che vi salverà la sanità mentale.

Nello specifico, questa guida si concentrerà su Apprise API, la versione webservice di Apprise. Mentre Apprise nasce come strumento a riga di comando, la sua versione API lo trasforma in un potente centralinista per le notifiche, accessibile tramite semplici chiamate HTTP.

Entrambi i progetti sono stati creati dalla stessa persona, Chris Caron conosciuto su Github come caronc.

Prerequisiti

Il metodo più semplice -nonché l'unico ufficialmente supportato- per installare Apprise API è tramite l'utilizzo di Docker, quindi avrete bisogno di una istanza di Docker.
Affinché i vostri programmi possano inviare chiamate all'endpoint API di Apprise, è necessario che essi possano raggiungerlo. Di conseguenza, se avete un firewall tra i due endpoint, dovrete creare una eccezione sulla porta 8000 (o quella che specificherete durante l'installazione).
Per ogni servizio che avrete intenzione di collegare, sono necessari parametri diversi che potete trovare indicati nella wiki del progetto Apprise. In questa guida vedremo un paio di esempi relativi a Invio di email tramite SMTP e Invio di notifiche tramite Telegram

Installazione

L'installazione di Apprise API, utilizzando Docker, è molto semplice. Vi basta creare un docker-compose ed utilizzarlo tramite l'omonimo comando:

Create una cartella per il progetto. In questo esempio creeremo una cartella apprise_api nella root del filesystem

sudo mkdir /apprise_api

Adesso, all'interno di questa cartella, creiamo le cartelle config, plugin ed attach che serviranno rispettivamente a contenere le configurazioni, i plugin custom e gli allegati

sudo mkdir /apprise_api/config
sudo mkdir /apprise_api/plugin
sudo mkdir /apprise_api/attach

Adesso creiamo il container di Apprise API col seguente comando docker run. Ricordatevi di indicare la porta TCP su cui Apprise API resterà in ascolto {{PORT}} ed i percorsi assoluti delle cartelle che avete creato al punto precedente (ai parametri -v)

docker run --name apprise \
   -p {{PORT}}:8000 \
   -e PUID=$(id -u) \
   -e PGID=$(id -g) \
   -v /apprise_api/config:/config \
   -v /apprise_api/plugin:/plugin \
   -v /apprise_api/attach:/attach \
   -e APPRISE_STATEFUL_MODE=simple \
   -e APPRISE_WORKER_COUNT=1 \
   -d caronc/apprise:latest

Una volta che Docker avrà terminato di scaricare (pull) le immagini e di creare il container, potrete accedere alla Web UI di Apprise API accedendo a http://indirizzo.IP.di.Docker:porta

Configurazione

Configurare i vostri canali di notifica preferiti con Apprise è semplice come scrivere un file di testo... E lo dico perché effettivamente è proprio così che si fa!

Premete su Configuration Manager nella barra laterale, poi sulla scheda Configuration.
Qui vi consiglio, per prima cosa, di indicare YAML nel parametro Format. L'altra opzione (TEXT) a lungo andare è molto più confusionaria, mentre la struttura del formato YAML renderà la consultazione della configurazione molto più semplice.

Adesso modifichiamo il nostro file di configurazione:

Prima di tutto, abbiamo bisogno di una intestazione:

urls:

Dentro a questa intestazione, per ogni canale di notifica da censire, creeremo un oggetto dando due spazi e il carattere -, seguito da un ulteriore spazio ( - ).

urls:
  -

❓

Perchè questi spazi?
YAML è un linguaggio di Markup che si basa sulla corretta identazione del suo contenuto. Inoltre, seguire queste regole di identazione semplifica enormemente la leggibilità di questo file.

Canale di notifica (email)

Adesso andiamo ad indicare ad Apprise quale canale di notifica vogliamo usare, indicandone l'identificativo seguito da ://, come se fosse un protocollo (alla fine... lo è!). In questo esempio, configuro l'integrazione email

urls:
  - mailtos://

💡

L'identificativo di ogni protocollo è reperibile nella Wiki di Apprise, per ogni servizio di notifica, alla voce Syntax.

Ora arriva la parte difficile. A seconda del provider di posta che stiamo usando, possiamo evitare di indicare certi parametri. Ecco alcuni esempi:

‼️

ATTENZIONE: Sicurezza delle Credenziali
Stai per inserire le tue credenziali in quello che, alla fine, è un file di testo. Assicurati che l'accesso alla configurazione di Apprise sia adeguatamente protetto.

Yahoo

urls:
  - mailtos://{utente}:{password}@[email protected]

Il campo utente è la parte dell'indirizzo Yahoo prima della @, per esempio in [email protected] l'utente da indicare è tizio.caio

Gmail

urls:
  - "mailtos://{utente}:{password}@[email protected]"

Il campo utente è la parte dell'indirizzo Gmail prima della @, per esempio in [email protected] l'utente da indicare è tizio.caio.

A differenza dell'esempio relativo a Yahoo, nota come la stringa sia racchiusa tra virgolette. Questo perché le App Password di Google contengono spazi, e per evitare errori di parsing è sempre necessario racchiudere la stringa tra virgolette.

💡

Se vuoi altre informazioni riguardo a questo ed altri problemi relativi -per esempio- alla presenza di caratteri speciali, puoi cercare tra i metodi di URL Encoding.

Alla data di scrittura di questa guida, per questo tipo di autenticazione, Google richiede di aver impostato la 2FA sul proprio account Google e l'utilizzo di una "App Password", invece della password dell'account Google. Vediamo insieme i passaggi per abilitare la 2FA ed ottenere una App Password:

Accedete a https://myaccount.google.com
Dal menu di sinistra, selezionate Sicurezza
Nella sezione Come accedi a Google, selezionare Verifica in due passaggi e seguire la procedura guidata per attivare la 2FA
Accedete ora a https://myaccount.google.com/apppasswords
Date un nome all'app (ad esempio, Apprise)
Copiate in un posto sicuro la vostra App Password, perché una volta premuto su Fine questa non verrà più mostrata

❗

Fai attenzione!
Anche gli spazi fanno parte della App Password, non cancellateli!

Altri provider email non direttamente supportati

Il vostro provider email non è nella lista dei servizi Built-In?
Non vi preoccupate, Apprise è estremamente versatile. Tuttavia dovremo dargli qualche parametro in più:

urls:
  - mailtos://{utente}:{password}@{dominio}:{porta}?smtp={indirizzo.server.smtp}&[email protected]:

Indicate la porta solamente se diversa dalla default (465) e, in quel caso, omettete anche il carattere :.

Utilizzo dei Tag

Avete fatto caso che in fondo alla riga del canale di notifica c'è il carattere :? Questo perché non basta configurare un canale di notifica, ma è necessario anche assegnargli un tag.

Più canali di notifica possono avere lo stesso tag, ed un canale di notifica può avere più tag.

I tag vengono utilizzati durante le chiamate API per indicare ad Apprise quali canali si vogliono notificare.

Facciamo un esempio pratico:

Per le email di errore, dobbiamo notificare:
- Il reparto tecnico
- Il responsabile
Per le mail di avviso, dobbiamo notificare:
- Il reparto tecnico

Invece di creare regole e parametri complessi per gestire queste casistiche, ci basta usare due tag:

urls:
  - mailtos://{utente}:{password}@{dominio}?to={[email protected]}
    - tag: avviso, errore
  - mailtos://{utente}:{password}@{dominio}?to={[email protected]}
    - tag: errore

In questo modo, inviando una chiamata API col tag avviso notificheremo solo il reparto tecnico, e indicando il tag errore avviseremo sia il reparto tecnico che il responsabile, tutto con una sola chiamata HTTP!

Se poi il responsabile vuole essere notificato anche sulla sua mail personale (ma lo stesso si applica anche a un canale di notifica diverso dalla email) basta creare due canali e dargli lo stesso tag:

urls:
  - mailtos://{utente}:{password}@{dominio}?to={[email protected]}
    - tag: avviso, errore
  - mailtos://{utente}:{password}@{dominio}?to={[email protected]}
    - tag: errore
  - mailtos://{utente}:{password}@{dominio}?to={[email protected]}
    - tag: errore

Canale di notifica (Telegram)

La configurazione del canale di notifica Telegram richiede molti meno parametri rispetto a quello delle email. Ci servono solo un Bot Token e uno o più Chat ID per indicare i destinatari.

Non sai di cosa stiamo parlando? Trovi tutte le informazioni sulla mia guida relativa alla creazione di un Bot di Telegram:

Di seguito un esempio di configurazione

urls:
  - tgram://BOT:TOKEN/CHATID:
    - tag: telegram_singolo

Nel caso di più destinatari, invece:

urls:
  - tgram://BOT:TOKEN/CHATID1/CHATID2/.../CHATIDN:
    - tag: telegram_multiplo

Di default, il messaggio viene inviato in testo semplice. Se volete formattare il messaggio tramite HTML o Markdown, potete aggiungere il parametro format come nell'esempio seguente:

urls:
  - tgram://BOT:TOKEN/CHATID1/CHATID2/.../CHATIDN/?format=markdown:
    - tag: telegram_markdown
  - tgram://BOT:TOKEN/CHATID1/CHATID2/.../CHATIDN/?format=html:
    - tag: telegram_html

💡

Se non specificate il formato qui, potrete comunque indicarlo durante la vostra chiamata ad Apprise API

Test di funzionamento dei canali impostati

Per testare il funzionamento dei canali che avete configurato, potete usare le comode funzionalità Review e Notifications nelle relative schede dentro a Configuration Manager:

Dentro a Configuration Manager, selezionate la scheda REVIEW

Selezionate uno o più dei tag che avete configurato (selezionando il tag all selezionerete tutti i canali configurati)
Adesso spostatevi nella scheda NOTIFICATIONS

Scrivete il testo del vostro messaggio in Body
Opzionalmente, indicate un titolo per la notifica in Title (nel caso di una email, questo sarà l'oggetto della mail)
Premete su SEND NOTIFICATION
Se avete configurato tutto correttamente, dovreste ricevere una notifica coi valori impostati

Utilizzo tramite API HTTP

Adesso arriva la parte migliore: implementare tutto questo nel vostro ambiente.

Trattandosi di un endpoint HTTP, che richiede l'invio di una chiamata POST, possiamo usare una miriade di metodi e comandi diversi per inviare notifiche tramite Apprise API.

Inoltre se andate su Configuration Manager, alla scheda OVERVIEW, troverete degli esempi già valorizzati con l'indirizzo IP, la porta ed il Configuration ID che state usando.

Il Configuration ID è l'identificativo univoco della tua configurazione. Lo trovi nella scheda OVERVIEW del Configuration Manager, già inserito negli URL di esempio.

Vediamo un paio di esempi utilizzando curl

Inviare un messaggio semplice

Ci bastano quattro righe (o una, se ci piacciono gli spaghetti nel codice):

curl -X POST \
	-F "body=Testo del messaggio" \
	-F "tags=tag_destinatari" \
	http://indirizzo.IP.di.Apprise:porta/notify/IdConfigurazione

Inviare un messaggio in Markdown

In questo caso, basta aggiungere il parametro format:

curl -X POST \
	-F "body=Testo del messaggio" \
	-F "tags=tag_destinatari" \
	-F "format=markdown" \
	http://indirizzo.IP.di.Apprise:porta/notify/IdConfigurazione

Inviare un messaggio con allegato(i)

Per aggiungere uno o più allegati, è necessario usare i parametri attach:

curl -X POST \
	-F "body=Testo del messaggio" \
	-F "tags=tag_destinatari" \
	-F attach1=@/percorso/dell/allegato1.txt \
	-F attach2=@/percorso/dell/allegato2.pdf \
	http://indirizzo.IP.di.Apprise:porta/notify/IdConfigurazione

Conclusioni

Come potete notare, non avremo mai più bisogno di indicare i parametri di invio email, il Bot Token o i Client ID, perché rimane tutto salvato sulla configurazione di Apprise API e possiamo andarla a richiamare tramite i tags.

Inoltre, trattandosi di una API, potremo usare Apprise API da più dispositivi e script senza configurarne più istanze!

Adesso che avete tutti i canali di notifica a disposizione da un solo endpoint, il limite è la vostra immaginazione.

Personalmente, Apprise mi ha salvato in più di una occasione quando un software che stavo usando aveva opzioni limitatissime per l'invio email, e durante lo sviluppo di vari programmi in cui le notifiche erano importanti ma non abbastanza da giustificare ore di ricerca e sviluppo per implementarle.

Spero che Apprise vi sia utile come lo è stato per me!