Panoramica
L'Integrazione Applicativa Aziendale (Enterprise Application Integration, EAI) di IncaMail permette alle organizzazioni di integrare la messaggistica sicura di IncaMail direttamente nel loro software aziendale, come sistemi ERP, piattaforme HR o soluzioni di gestione documentale. Questo consente l'invio automatizzato e conforme di messaggi riservati, personali o raccomandati (ad esempio buste paga, fatture o avvisi legali) senza alcun passaggio manuale da parte dell'utente finale.
Ci sono quattro passaggi principali per iniziare: iscriversi a un abbonamento, registrare il proprio account amministratore e gli account mittenti che il software aziendale utilizzerà per inviare messaggi, quindi completare la configurazione tecnica scegliendo e configurando il metodo di integrazione più adatto alla propria infrastruttura.
Questo articolo ti guida attraverso ogni passaggio e spiega i metodi di integrazione disponibili, così potrai scegliere l'approccio giusto per il tuo caso d'uso.
Prerequisiti
Prima di iniziare, assicurati che quanto segue sia a posto:
- Contratto aziendale IncaMail: La tua organizzazione deve essere un cliente aziendale registrato di IncaMail con un contratto valido che includa l'opzione EAI.
- Risorse per sviluppatori: Per le integrazioni SOAP e REST API, sono necessari sviluppatori familiari con SOAP o REST nel loro ambiente di programmazione.
- Accesso al firewall: A seconda del metodo di integrazione, la porta 587 (SMTP/TLS Auth) o la porta 25 (Integrazione Dominio) non devono essere bloccate dal firewall.
- Se si utilizza l'Integrazione Dominio: Proprietà del dominio - Devi poter verificare la proprietà del/dei dominio/i dal quale verranno inviati i messaggi.
Passaggio 1 – Registrare un Account
Se non hai già un account IncaMail, registrane uno prima. L'indirizzo email usato durante la registrazione fungerà da account amministratore.
👉 Registrati qui: https://app.incamail.com/en/register
Nota: Ogni indirizzo email che verrà utilizzato per inviare messaggi dal tuo software aziendale deve essere registrato individualmente sulla piattaforma IncaMail prima di poter essere autorizzato per l’uso con qualsiasi metodo di integrazione EAI.
Passaggio 2 – Iscriversi a un Abbonamento Business
La funzionalità EAI richiede un abbonamento business IncaMail attivo con l’opzione EAI abilitata. È disponibile una prova gratuita di 30 giorni senza alcun impegno.
👉 Iscriviti qui: https://web.incamail.com/en/e-mail-encryption/incamail-for-the-e-mail-client
Nota: Iscriversi a una prova non costituisce un ordine vincolante. Puoi valutare l’integrazione durante il periodo di prova prima di decidere se procedere.
Passaggio 3 – Scegli il Metodo di Integrazione
EAI offre quattro metodi di integrazione. La scelta giusta dipende dalle capacità del tuo software aziendale e dalla tua infrastruttura:
| Metodo | Descrizione | Ideale per |
|---|---|---|
| SMTP/TLS Auth | IncaMail agisce come un server SMTP autenticato standard. Facile da configurare in qualsiasi linguaggio di programmazione o software che supporti SMTP. | Software aziendale con capacità di invio SMTP integrate |
| Integrazione Dominio (EAI su MGI) | Invio tramite il tuo server di posta aziendale esistente usando SMTP su TLS/SSL. | Ambienti dove MGI è già in uso, o dove i messaggi inviati devono essere archiviati nelle caselle di posta |
| SOAP API | Tre potenti API (Send, Read, Admin) per massima flessibilità, tracciamento dei messaggi, decrittazione dei messaggi ricevuti e gestione dell’account. | Integrazioni personalizzate in SAP e altri sistemi aziendali che richiedono tracciamento o decrittazione |
| REST API | Invio moderno basato su REST con supporto per allegati di grandi dimensioni (fino a 1 GB) e tracciamento della consegna. | Applicazioni web e ambienti di sviluppo moderni |
Passaggio 4 – Completa la Configurazione Tecnica
Puoi trovare la guida tecnica completa per configurare l’Enterprise Application Integration qui: https://support.incamail.com/hc/article_attachments/23166869784466
SMTP/TLS Auth
IncaMail si comporta come un normale agente di trasferimento posta SMTP (MTA). I messaggi vengono inviati usando SMTP standard con autenticazione TLS, e il tipo di consegna è specificato tramite tag nella riga dell’oggetto.
Dettagli server:
| Produzione | Integrazione / Test | |
|---|---|---|
| Server SMTP |
incamail.com (ricerca MX) o gw1.incamail.com (statico) |
sta.incamail.com (ricerca MX) o gw1.sta.incamail.com (statico) |
| Porta | 25 o 587 | 25 o 587 |
| Autenticazione | Basic Auth (username = indirizzo email mittente, password = definita dall’utente durante la registrazione) | Stesso |
| Cifratura | STARTTLS (obbligatorio prima dell’invio della password) | Stesso |
Importante: STARTTLS deve essere attivato prima della trasmissione della password. Senza TLS, la connessione a IncaMail non è protetta. L’indirizzo email usato per l’autenticazione deve corrispondere all’indirizzo mittente nell’intestazione
FROM:.
Tag nella riga dell’oggetto per il tipo di consegna:
-
<im> <c>— Riservato -
<im> <p>— Personale -
<im> <r>— Raccomandato
Esempio di oggetto: <im> <c> Busta Paga 12/2024
Integrazione Dominio (EAI su MGI)
Questo metodo si utilizza quando:
- La tua organizzazione usa già IncaMail MGI e un software aziendale deve inoltre inviare tramite la stessa infrastruttura.
- I messaggi inviati devono essere archiviati nelle caselle di posta per scopi di archiviazione.
- Il tuo software aziendale utilizza già un server di posta aziendale per l’email in uscita.
⚠️ Importante — Assistenza per la Configurazione: A differenza degli altri metodi di integrazione EAI, l’Integrazione Dominio (EAI su MGI) non può essere configurata completamente in self-service. Poiché l’invio avviene tramite il tuo server di posta aziendale e non direttamente via SOAP, TLS Auth o REST, è necessaria una configurazione aggiuntiva lato IncaMail. Contatta il Supporto IncaMail per avviare la configurazione: 👉 https://support.incamail.com/hc/en-us/requests/new
Per la configurazione del dominio MGI, consulta la Guida alla Configurazione MGI.
Tag nella riga dell’oggetto e formato degli indirizzi destinatari:
| Campo | Formato | Esempio |
|---|---|---|
| Oggetto | Prependere il tag del tipo di consegna | <im> <c> Busta Paga 12/2024 |
| A / CC / Ccn | Appendere .incamail.ch a ogni indirizzo destinatario |
john.doe@gmail.com.incamail.ch |
SOAP API
La SOAP API fornisce tre API separate per la massima flessibilità:
| API | Scopo |
|---|---|
| SOAP Send | Inviare messaggi e tracciare lo stato di consegna |
| SOAP Read | Decriptare messaggi IncaMail (SAFE) ricevuti e criptati |
| SOAP Admin | Modificare i dati dell’account cliente aziendale (nome azienda, banner, logo) |
Endpoint di produzione:
| URL | |
|---|---|
| SOAP Send | https://ws.incamail.com/3.0/ |
| SOAP Read | https://wsread.incamail.com/3.0/IncaMailReadService |
| SOAP Admin | https://wsmgmt.incamail.com/IncaMailAdminService/IncaMailAdminPort |
Endpoint di test / integrazione:
| URL | |
|---|---|
| SOAP Send | https://ws.sta.incamail.com/3.0/ |
| SOAP Read | https://wsread.sta.incamail.com/3.0/IncaMailReadService |
| SOAP Admin | https://wsmgmt.sta.incamail.com/IncaMailAdminService/IncaMailAdminPort |
Importante: Includi sempre la barra finale
/negli URL degli endpoint dove indicato. Usa sempre la piattaforma di integrazione durante sviluppo e test — passa alla piattaforma di produzione solo per l’uso in produzione.
Autenticazione: Basic Authentication (Preemptive) via HTTPS. Username = indirizzo email IncaMail registrato, password = definita dall’utente durante la registrazione.
Certificato SSL: Alcuni sistemi (ad esempio SAP) richiedono che il certificato root SSL del server IncaMail sia registrato. Scarica qui il certificato SwissSign Gold CA – G2:
- PEM:
https://swisssign.net/cgi-bin/authority/download/5B257B96A465517EB839F3C078665EE83AE7F0EE.pem
Per esempi dettagliati di richieste SOAP, definizioni WSDL e istruzioni specifiche per SAP, consulta la Guida Completa all’Integrazione EAI: 👉 https://support.incamail.com/hc/article_attachments/23166869784466
REST API
La REST Send API offre un’alternativa moderna e leggera per inviare messaggi e tracciare lo stato di consegna, con supporto integrato per allegati di grandi dimensioni fino a 1 GB.
URL base:
| URL | |
|---|---|
| Produzione | https://incamail.com/xapi/send/v1/ |
| Integrazione / Test | https://sta.incamail.com/xapi/send/v1/ |
Endpoint principali:
| Endpoint | Metodo | Scopo |
|---|---|---|
/ping |
GET | Verifica connessione |
/message/send |
POST | Invia un messaggio IncaMail |
/message/prepareFile |
POST | Pre-carica un allegato di grandi dimensioni (fino a 1 GB) |
/sentMessages/getDeliveryState |
POST | Traccia lo stato di consegna tramite ID messaggio |
Autenticazione: Basic Auth (indirizzo email + password).
Autorizzazione: Ogni indirizzo email mittente deve essere esplicitamente autorizzato dal Supporto IncaMail prima dell’uso. Contatti: business@incamail.ch fornendo gli indirizzi email mittenti e la piattaforma (integrazione o produzione) da utilizzare.
Documentazione OpenAPI: https://incamail.com/apidef/restsend/index.html
Per esempi dettagliati di richieste REST e istruzioni di configurazione Postman, consulta la Guida Completa all’Integrazione EAI: 👉 https://support.incamail.com/hc/article_attachments/23166869784466
Tipi di Consegna
In tutti i metodi di integrazione sono disponibili i seguenti tipi di consegna:
| Tipo di Consegna | Valore SOAP/REST | Tag Oggetto | Descrizione |
|---|---|---|---|
| Riservato | enc |
<im> <c> |
Cifrato se il destinatario non è su un dominio TLS; firmato e non cifrato per destinatari MGI |
| Personale | encPersonal |
<im> <p> |
Sempre cifrato, anche per destinatari MGI |
| Raccomandato | reco |
<im> <r> |
Legalmente verificabile con ricevuta di consegna e accettazione |
| Solo firmato | plain_signed |
— | Firmato ma non cifrato (solo REST API) |
Comprendere la Cifratura dei Messaggi (Formato SAFE)
IncaMail utilizza il formato brevettato SAFE (Secure Attached File Encryption) per trasportare i messaggi cifrati. A seconda della configurazione del destinatario, viene utilizzato uno dei seguenti metodi di consegna:
- Consegna TLS: Per i destinatari con integrazione dominio MGI, i messaggi sono consegnati cifrati tramite TLS direttamente al loro gateway di posta.
-
Allegato SAFE: Per tutti gli altri destinatari, l’intero messaggio è cifrato in un allegato SAFE (
IncaMail.html). Il destinatario decripta il messaggio tramite l’interfaccia web IncaMail, l’app mobile o un’integrazione SOAP Read. - Ibrido: Come SAFE, ma con un pulsante "Leggi" aggiuntivo per un accesso più rapido.
L’applicazione di invio non deve gestire la cifratura — IncaMail la gestisce automaticamente in base alla configurazione del destinatario.
Domande Frequenti
Tutti gli account mittenti devono essere registrati individualmente? Sì. Ogni indirizzo email usato per inviare messaggi tramite qualsiasi metodo EAI deve essere registrato individualmente sulla piattaforma IncaMail e autorizzato per il metodo di integrazione pertinente.
Posso usare la SOAP API senza un contratto EAI separato? No. Deve essere attivo un contratto aziendale IncaMail valido con l’opzione EAI configurata da IncaMail prima che l’API possa essere utilizzata.
Posso usare più metodi di integrazione in parallelo? Sì. Ad esempio, un’organizzazione può usare SOAP Send per la consegna automatica delle buste paga e l’Integrazione Dominio per messaggi inviati manualmente tramite Outlook — entrambi possono funzionare simultaneamente sotto lo stesso contratto.
Quanti thread SOAP paralleli posso usare? Raccomandiamo un massimo di quattro thread paralleli per l’invio di richieste SOAP al server IncaMail per evitare problemi di performance.
Dove posso testare senza influire sulla produzione? Usa la piattaforma di integrazione/test (sta.incamail.com / ws.sta.incamail.com) durante lo sviluppo. Passa sempre agli endpoint di produzione prima di andare in live.