Mailstrom 1.5.0

🌪️ Mailstrom

Client .NET per Pack-a-Mail, il servizio di invio massivo di email scritto in Go. Nasce per un problema concreto: far spedire decine di migliaia di email a un gestionale VB.NET senza che chi lo mantiene debba conoscere le insidie del protocollo.

using var client = new MailstromClient("http://127.0.0.1:8080", "pk_...");
BulkResult esito = await client.SendBulkAsync(richiesta);   // 40.000 destinatari, una riga

✨ Cosa fa per te

📦 Installazione

dotnet add package Mailstrom

Target supportati: .NET Standard 2.0 (quindi .NET Framework 4.6.2 e successivi: WinForms, WebForms, servizi Windows) e .NET 8.

🚀 Avvio rapido — C#

using Mailstrom;
using Mailstrom.Bulk;
using Mailstrom.Models.Requests;

using var client = new MailstromClient("http://127.0.0.1:8080", "pk_...");

var richiesta = new CampaignRequest
{
    Name = "Solleciti giugno",
    Defaults = new RecipientDefaults
    {
        From = "Amministrazione <amministrazione@azienda.it>",
        Subject = "Sollecito per la fattura {{numero}}",
        Template = new MailTemplate
        {
            Html = "<p>Gentile {{nome}}, risulta insoluta la fattura {{numero}}.</p>",
        },
    },
};

foreach (DataRow riga in tabellaInsoluti.Rows)
{
    richiesta.AddRecipient((string)riga["IdDocumento"], (string)riga["Email"])
             .WithField("nome", riga["RagioneSociale"])
             .WithField("numero", riga["NumeroFattura"]);
}

BulkResult esito = await client.SendBulkAsync(richiesta);
Console.WriteLine($"Campagna {esito.CampaignId}: accodati {esito.Accepted}.");

🚀 Avvio rapido — VB.NET

Tutto sincrono, come in un gestore di evento WinForms. Nessun Await, nessun rischio di stallo.

Dim client As MailstromClient = MailstromClient.Create() _
    .WithEndpoint("192.168.1.10", 8080) _
    .WithApiKey("pk_...") _
    .WithUserAgent("Gestionale/2026.1") _
    .Build()

Using client
    Dim richiesta As New CampaignRequest()
    richiesta.Name = "Solleciti giugno"
    richiesta.Defaults.From = "Amministrazione <amministrazione@azienda.it>"
    richiesta.Defaults.Subject = "Sollecito per la fattura {{numero}}"
    richiesta.Defaults.Template = New MailTemplate() With {
        .Html = "<p>Gentile {{nome}}, risulta insoluta la fattura {{numero}}.</p>"
    }

    For Each riga As DataRow In tabellaInsoluti.Rows
        richiesta.AddRecipient(CStr(riga("IdDocumento")), CStr(riga("Email"))) _
                 .WithField("nome", riga("RagioneSociale")) _
                 .WithField("numero", riga("NumeroFattura"))
    Next

    Dim esito As BulkResult = client.SendBulk(richiesta)
    MessageBox.Show("Accodate " & esito.Accepted & " email.")
End Using

Perche' AddRecipient restituisce il destinatario. VB.NET non ha gli inizializzatori di raccolta di C#: senza il concatenamento, ogni riga del ciclo richiederebbe una variabile temporanea e tre istruzioni in piu'.

📊 Seguire l'invio

// Attesa con avanzamento — in WinForms Progress<T> notifica sul thread dell'interfaccia,
// quindi si puo' aggiornare direttamente una ProgressBar.
CampaignInfo finale = await client.WaitForCompletionAsync(
    esito.CampaignId,
    pollInterval: TimeSpan.FromSeconds(5),
    timeout: TimeSpan.FromHours(2),
    progress: new Progress<CampaignProgress>(p => barra.Value = p.Percent),
    cancellationToken);

// Il rapporto: quante non sono arrivate, e perche'.
FailureReport rapporto = await client.GetFailureReportAsync(esito.CampaignId, cancellationToken);
foreach (CategoryCount causa in rapporto.NotSent.ByCategory)
{
    Console.WriteLine($"{causa.Description}: {causa.Count}");
}

// Il dettaglio, con la chiave del gestionale per riconciliare l'anagrafica.
await foreach (MessageInfo m in client.EnumerateMessagesAsync(
    esito.CampaignId, new MessageFilter { Status = MessageStatus.Dead }, cancellationToken))
{
    Console.WriteLine($"{m.Id} → {m.To}: {m.FailureReason}");
}

// Oppure l'esportazione completa, in streaming su file.
await client.ExportMessagesCsvAsync(esito.CampaignId, @"C:\report.csv", cancellationToken);

⚙️ Configurazione

Tre modi di costruire il client, tutti equivalenti:

new MailstromClient("http://127.0.0.1:8080", "pk_...");            // minimale
MailstromClient.Create().WithEndpoint("srv", 8080).WithApiKey("pk_...").Build();   // guidato
services.AddMailstrom(o => { o.BaseAddress = …; o.ApiKey = …; });   // ASP.NET Core (net8.0)

Una configurazione incompleta fallisce alla costruzione con MailstromConfigurationException, non al primo invio: un gestionale deve accorgersene all'avvio.

🧯 Errori

try
{
    await client.SendBulkAsync(richiesta, cancellationToken);
}
catch (MailstromValidationException ex)      // 400: dati sbagliati
{
    foreach (FieldError e in ex.FieldErrors) log.Warn($"{e.Field}: {e.Message}");
}
catch (MailstromBulkException ex)            // campagna creata ma incompleta
{
    log.Error($"Campagna {ex.CampaignId} incompleta: {ex.AcceptedRecipients}/{ex.TotalRecipients}");
}
catch (MailstromTransportException ex)       // servizio irraggiungibile
{
    log.Error(ex.Message);
}

La tabella completa e' in docs/04-gestione-errori.md. Ogni MailstromApiException porta il RequestId assegnato dal servizio: e' la chiave per ritrovare l'episodio nei log di Pack-a-Mail.

📚 Documentazione

🧪 Sviluppo

dotnet build   Mailstrom.sln -c Release     # entrambi i target, zero avvisi
dotnet test    tests/Mailstrom.Tests        # prove unitarie
dotnet pack    src/Mailstrom -c Release     # pacchetto + simboli

Le prove contro un'istanza reale sono in tests/Mailstrom.IntegrationTests e non partono da sole:

export MAILSTROM_TEST_URL=http://127.0.0.1:8080
export MAILSTROM_TEST_KEY=pk_...
dotnet test tests/Mailstrom.IntegrationTests

Dalla versione multi-cliente, smtp.provider: file e validation.mode: syntax non sono piu' chiavi di config.yml: si impostano dalla dashboard "Impostazioni" sul cliente in uso, oppure — per un ambiente di prova senza browser — si adottano da config.yml al primo avvio (vedi config.example.yml del servizio, Parte 2, e packamail api-key add -tenant <slug> per ottenere la chiave). Con smtp.provider: file nessuna email parte davvero; con validation.mode: syntax le modalita' con DNS non scarterebbero in blocco i domini di prova. Il tetto sui destinatari per campagna (validation.max_recipients_per_request) nasce a 100.000 su un cliente nuovo e di norma non va toccato per una prova — vedi docs/01-configurazione.md.

I due progetti in samples/ sono eseguibili e puntano allo stesso servizio:

dotnet run --project samples/Sample.VbNet  -- http://127.0.0.1:8080 pk_... 25
dotnet run --project samples/Sample.CSharp -- http://127.0.0.1:8080 pk_... 25

📎 Allegati

Sono un parametro facoltativo. Nullo o vuoto significa nessun allegato, e non costa nemmeno una chiamata di rete in piu':

using var listino = MailstromAttachment.FromFile(@"C:\documenti\listino.pdf");

BulkResult esito = await client.SendBulkAsync(
    richiesta, new[] { listino }, progresso, CancellationToken.None);

In VB.NET, sincrono:

Dim allegati As New List(Of MailstromAttachment)()
allegati.Add(MailstromAttachment.FromFile("C:\documenti\listino.pdf"))
Try
    Dim esito As BulkResult = client.SendBulk(richiesta, allegati, avanzamento)
Finally
    For Each a As MailstromAttachment In allegati
        a.Dispose()
    Next
End Try

L'allegato vale per l'intera campagna: lo stesso file raggiunge tutti i destinatari, e viene caricato una volta sola prima del primo blocco — trentamila destinatari non moltiplicano i megabyte trasmessi. Il caricamento precede la creazione della campagna, cosi' un file irraggiungibile ferma l'invio quando non e' ancora partito nulla.

Per un logo referenziato dal corpo HTML come cid::

using var logo = MailstromAttachment.InlineFromFile(@"C:\img\logo.png", "logo");
// nel template: <img src="cid:logo">

Dettagli in docs/07-allegati.md.

🗂️ Template salvati sul servizio

Un template si puo' salvare una volta e riferire da piu' campagne, invece di ripeterlo inline a ogni invio:

await client.SaveTemplateAsync("marketing/newsletter", new SaveTemplateRequest
{
    Name = "Newsletter mensile",
    Html = "<p>Gentile {{nome}}, ...</p>",
}, cancellationToken);

richiesta.Defaults.TemplateId = "marketing/newsletter";   // al posto di Defaults.Template

ListTemplatesAsync, GetTemplateAsync, RenderTemplateAsync (rendering ad-hoc senza salvare) e DeleteTemplateAsync completano la libreria. Richiede che Pack-a-Mail abbia la libreria template montata su quell'istanza: se non lo e', ogni chiamata solleva MailstromServerException con ProblemType == "/problems/not-configured" — non transitorio, non ha senso ritentare. Dettagli in docs/05-mappatura-api.md.

📋 Fuori portata

Non per scelta di questa libreria, ma perche' il servizio non li espone: webhook e notifiche push — lo stato si ottiene per osservazione.

📄 Licenza

MIT.