Guide di integrazione, API e best practice per inviare email dal frontend.
Per iniziare
Cos'e MailingCore, per chi e pensato e come si integra nel tuo stack.
Tenant, API key, scope, template e altri termini del prodotto.
Primo invio con API key in meno di 10 minuti.
Inviare email transazionali aprendo un'incidenza helpdesk da un flusso Botpress di assistenza clienti.
SDK browser vs API server, code e responsabilita.
URL API, chiavi mc_live/mc_test e staging.
Verifica dominio, quota e soppressioni prima della produzione.
SDK JavaScript
mailingcore-js — init, send e gestione errori.
Installare mailingcore-js — npm e stato pubblicazione.
MailingCore.init — apiKey, baseUrl e timeout.
templateVersionId — inviare versioni pubblicate.
Reinvii sicuri con idempotencyKey — stessa chiave, stessa risposta.
MailingCoreError — codici di stato e recupero.
Server Actions — tenere la API key fuori dal client.
Elenca le email inviate e il loro stato dall'SDK JavaScript.
API REST
JWT per il pannello e API key per le integrazioni.
Creare chiavi, assegnare permessi e ruotare credenziali.
Header X-Tenant-Id e isolamento dei dati.
POST /emails/send — payload, risposta e template.
Formato errori HTTP e cause frequenti.
Header X-Quota, grace period e blocco.
POST /emails/batch — fino a 100 destinatari con variabili per destinatario.
GET /emails/logs — cronologia paginata degli invii del tenant.
Throttling, limiti auth e header X-RateLimit-*.
POST/GET/DELETE /scheduled-emails — invii transazionali differiti.
Metriche aggregate di aperture, clic e bounce tramite l'API REST.
Template
Draft vs Published e invio con templateVersionId.
POST .../publish, CSS inline e annullamento pubblicazione.
Sintassi {{var}}, unsubscribeUrl e variabili dichiarate.
GET /library e POST clone — template di sistema per il tenant.
Editor dashboard — Monaco, Unlayer e versioni bozza.
locale e localeGroupId — versioni multi-lingua.
Consegna
Perche verificare il dominio prima della produzione.
Record SPF, DKIM e DMARC generati da MailingCore.
Controllare SPF, DKIM e DMARC dopo la configurazione DNS.
Bloccare invii a indirizzi con bounce, reclamo o disiscrizione.
Pixel di tracking e redirect link per metriche di engagement.
fromEmail, fromName e replyTo su domini verificati.
Soppressione hard bounce, webhook SES e evento email.bounced.
Cosa memorizza il tracking di aperture/clic, come disattivarlo e disiscrizione in un clic.
Newsletter
Modello contatto, externalId, locale e filtri audience.
PUT /contacts — upsert per email con externalId e attributi.
POST /contacts/bulk — upsert fino a 1000 contatti per richiesta.
Pagine ospitate /u/:token, {{unsubscribeUrl}} e webhook contact.unsubscribed.
Stati, audience filter, fan-out asincrono e statistiche.
Flusso test → schedule → send con POST /campaigns.
GET /campaigns/:id/locale-coverage e routing varianti multi-lingua.
Sync contatti, API campagne e webhook bidirezionali per newsletter embedded.
Automazione
Automazioni drip a step: invia e attendi, con iscrizione dei contatti e ciclo di vita proprio.
Step SEND_EMAIL e WAIT, ritardi, regole di attivazione e modifica solo in DRAFT.
Iscrivi i contatti in una sequenza attiva, ciclo di vita dell'iscrizione e stato reale dei trigger.
Metti alla prova due versioni di un template in una campagna e scegli la vincente per tasso di apertura.
Webhook
Eventi, registrazione endpoint e retry.
Validare X-MailingCore-Signature sul tuo server.
Riferimento payload per email.* e contact.unsubscribed.
Registrare POST /webhooks/endpoints con scope webhooks:manage.
Log consegne, policy retry BullMQ e gestione idempotente.
Piani e limiti
Limiti per piano, quote e fatturazione Stripe.
Avviso all'80 %, grazia al 110 % e blocco 429.
Stripe Checkout per cambi piano e Customer Portal per gestire i pagamenti.
Grant mensili, pack one-time e consumo sugli endpoint /ai.
Limiti di richiesta, dimensione, batch e rate applicati dall'API di MailingCore.
Assistente IA
Genera e migliora i template email con l'IA dall'editor o dall'API /ai.
Gli endpoint /ai/generate, /ai/generate-template e /ai/improve, l'hard block 402 e il limite 20/min.
Sicurezza e GDPR
Hosting europeo, posizionamento GDPR e confini dei dati.
DELETE /contacts/:externalId — diritto all'oblio.
Rotazione, separazione ambienti e nessuna esposizione client.
Eliminare un tenant/account e cosa viene cancellato rispetto a cosa resta (GDPR).
Dashboard
Tour del pannello web MailingCore: email, template, domini e impostazioni.
Creare, copiare e assegnare scope alle API key dal pannello.
Attivare 2FA TOTP per admin del pannello.
Invitare admin, assegnare ruoli e gestire la membership del tenant.
KPI aggregati, trend giornalieri e top template da pannello e API.
Integrazioni
Invia tramite il tuo server SMTP (per esempio Gmail) per progetto.
MailingCore Forms — crea moduli di contatto che consegnano tramite l'API di MailingCore.
Fai inviare email agli agenti IA tramite MailingCore con il server MCP e docs leggibili dagli agenti.
Riferimento
Swagger UI interattivo e schema JSON su api.mailingcore.com.
Glossario pubblico abbreviato dei termini MailingCore.
Maturita del prodotto, hosting, disponibilita SDK e dati in UE.
Gli stati del ciclo di vita di un log email e cosa significa ciascuno.
