Magnews REST API – Guida introduttiva

La REST API di magnews ti permette di integrare magnews ai tuoi sistemi (CRM, eCommerce, siti web, data platform) e automatizzare attività come gestione contatti, campagne, contenuti e webhooks. 

In questa pagina trovi una panoramica generale e i concetti fondamentali per iniziare a lavorare con le API.

Se cerchi il dettaglio completo di endpoint, parametri e payload, consulta la Reference Guide.

Se vuoi partire velocemente con i test, puoi usare la Postman collection ufficiale: trovi richieste già pronte, esempi e una struttura ordinata per risorsa (contatti, comunicazioni, insights, ecc.).

Cosa puoi fare con la REST API

La REST API di magnews è organizzata per aree funzionali.

Contacts

Gestione completa dell’anagrafica contatti:

• creare, aggiornare, unire (merge) o cancellare contatti;
• gestire stati di iscrizione (subscribe / unsubscribe / suspend);
• interrogare i contatti tramite query MQL;
• aggiungere o rimuovere contatti da audience statiche;
• far entrare i contatti nei workflow;
• eseguire operazioni massive (batch merge, batch delete).

Audiences

Gestione delle audience utilizzate come target di campagne e automazioni:

• recuperare audience esistenti;
• creare e cancellare audience statiche;
• interrogare audience tramite query;
• utilizzare le audience come target per comunicazioni e spedizioni.

Communications & Deliveries

Area dedicata alle comunicazioni marketing (newsletter) e alle relative spedizioni:

• recuperare e aggiornare informazioni di newsletter e template;
• avviare una spedizione;
• gestire pianificazioni (immediate, programmate, periodiche, in più fasi);
• monitorare lo stato delle spedizioni;
• mettere in pausa, riprendere o interrompere una spedizione.

Transactional (Simple Messages)

Invio di messaggi transazionali (chiamati Simple Messages nella API):

• invio di email e SMS singoli;
• invio batch di messaggi transazionali;
• invio MIME raw;
• consultazione dello stato dei messaggi tramite ID interno o ID esterno.

Webhooks

Integrazione event-driven tramite notifiche push:

• creare e configurare webhook;
• attivare, sospendere o cancellare sottoscrizioni;
• consultare lo storico e lo stato dei webhook.

Insights

Analisi delle performance di campagne, transazionali e workflow:

• statistiche di comunicazioni e delivery: aperture, click, conversioni,..;
• report aggregati o filtrati per audience, delivery o query;
• insight su messaggi transazionali;
• insight su workflow.

Tabelle dati

Gestione delle tabelle dati ed estensioni contatto (entities) e dei dati applicativi:

• creare, aggiornare e interrogare record di entità custom;
• utilizzo di MQL per query avanzate su dati di sistema e custom.

Export e operazioni asincrone

• lanciare attività pianificate (scheduled work);
• esportare i dati di sistema e di tabelle dati personalizzate, tramite query MQL.

Account

Endpoint di servizio e di contesto:

• recuperare informazioni sull’utente e sull’account;
• verificare i crediti residui per canale (email, sms);

Base URL e “versione” delle API

Le chiamate partono da una base URL del tipo:

https://ws-mn1.mag-news.it/ws/rest/api

Autenticazione

Ogni richiesta deve essere autenticata. Il metodo consigliato è OAuth 2.0, usando un access token nell’header Authorization:

Authorization: Bearer <access_token>

In alcune integrazioni possono essere supportati anche metodi alternativi (ad esempio Basic Authentication o token in query string), ma per motivi di sicurezza è preferibile usare Bearer token.

OAuth 2.0: setup rapido 

1) Crea un certificato digitale

Per generare token OAuth devi creare le credenziali della tua applicazione:

1. Su magnews vai in Impostazioni > Web service > Certificati digitali
2. Crea un nuovo certificato di tipo Applicazione Client (OAuth 2.0).
3. Salva Application ID e App Secret in modo sicuro: ti serviranno per ottenere i token.

Se stai testando il flusso interattivo direttamente in Postman, imposta come Redirect URI:

https://oauth.pstmn.io/v1/browser-callback

Se invece integri un’applicazione tua, usa la redirect URI della tua app. Se generi token manualmente da magnews, puoi lasciarla vuota.

2) Genera un access token

Hai due opzioni:

• Modalità interattiva: usa le richieste che trovi in Token management della collection Postman (Authorization Code Flow) e segui le istruzioni presenti nell’overview.
• Modalità manuale: in piattaforma vai su Impostazioni > Web service > Gestione token, seleziona certificato e utente, poi crea il token e copia access token (e, se disponibile, refresh token).

3) Imposta le variabili in Postman

Nelle variabili della collection (o dell’environment) compila:

4) Sei pronto

A questo punto puoi iniziare a esplorare le cartelle della collection e testare le richieste sulle risorse principali (contatti, campagne, insights e così via).

Refresh del token

Se il token scade, puoi rigenerarlo:

• in Postman, usando la richiesta Refresh token nella cartella Token management;
• in modo programmatico, implementando una chiamata di refresh nel tuo sistema (vedi l'esempio nella collection).

Rate limits

Per mantenere stabile il servizio, le API applicano limiti di frequenza configurati per account. Se superi la soglia prevista nell’intervallo di tempo, riceverai:

429 Too Many Requests

Buona pratica: in caso di 429, implementa un meccanismo di retry con backoff (attese progressive) per evitare nuovi superamenti.

Codici di stato ed errori

Le risposte usano codici HTTP standard, tra cui:

• 200 OK: richiesta completata correttamente.
• 400 Bad Request: parametri mancanti/non validi o payload malformato.
• 401 Unauthorized: autenticazione assente, errata o token scaduto.
• 403 Forbidden: permessi insufficienti o restrizioni di sicurezza (es. WAN Forbidden).
• 404 Not Found: risorsa inesistente.
• 429 Too Many Requests: superato rate limit.
• 500 Internal Server Error: errore imprevisto lato server.

Dettaglio errore (MNError)

In alcuni casi, oltre al codice HTTP, la risposta include un oggetto di dettaglio utile per capire cosa correggere. Puoi trovare campi come:

• errorType: categoria dell’errore (es. EmptyValue, ValueNotValid, UniqueConstraintViolation).
• fieldRef: riferimento al campo che ha generato l’errore.
• debugExplanation: spiegazione testuale per facilitare il debug.

Prossimi step consigliati

1. Importa (o fai fork di) la Postman collection e configura le variabili.
2. Verifica l’autenticazione con una chiamata semplice (es. lettura di una risorsa di test).
3. Passa alle risorse chiave per la tua integrazione (come i contacts e gli insights).
4. Quando vai in produzione, aggiungi gestione di refresh token, errori (400/401/429) e logging.

Postman collection

Per facilitare l’esplorazione e il testing delle API, magnews mette a disposizione una collection Postman ufficiale che include:

• richieste già pronte per i principali endpoint REST;
• gestione dei token OAuth 2.0;
• struttura organizzata per risorsa (contatti, campagne, insights, webhooks, ecc.).

Puoi forkare la collection nel tuo workspace Postman e mantenerla aggiornata tramite pull periodici, così da avere sempre accesso alle ultime novità e agli endpoint più recenti senza dover ricreare le richieste da zero.

GitHub

Magnews è presente anche su GitHub con una serie di progetti open source pensati per sviluppatori e integratori.

Se ti piace esplorare e sperimentare:

• dai un'occhiata ai repository disponibili;
• lascia una ⭐ se trovi qualcosa di utile;
• fai un fork o contribuisci con miglioramenti e nuove idee.

È il modo migliore per restare aggiornato sull’ecosistema magnews e partecipare attivamente allo sviluppo delle integrazioni.