Recapitabilità e rimbalzi tramite API e MCP

La dashboard di TrekMail mostra due tipi di dati sui rimbalzi nella scheda Statistiche di ogni dominio:

1. Un riepilogo di 30 giorni: conteggi di messaggi inviati, consegnati e con rimbalzo soft o hard, oltre ai tassi di consegna e rimbalzo.
2. Un elenco per destinatario: gli ultimi 50 rimbalzi in uscita con il codice di stato SMTP e la risposta del server ricevente, per capire perché uno specifico messaggio non è stato consegnato.

Entrambi sono ora disponibili tramite l’API REST e il server MCP. Un agente può recuperare i motivi dei rimbalzi, riepilogare lo stato della reputazione e alimentare i flussi di pulizia delle liste senza mai aprire la dashboard.

Dati disponibili

Tutti e tre richiedono domains:read (oppure mailboxes:read per l’elenco relativo alla casella). Sono di sola lettura. Non serve alcuna chiave di idempotenza.

L’API usa gli stessi dati di recapitabilità delle schede statistiche della dashboard, quindi le due viste restano allineate.

API REST: esempi rapidi

Riepilogo dominio

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status è lo stesso indicatore a tre stati mostrato dalla dashboard:

• good: tasso di rimbalzo inferiore al 2%.
• warning: tasso di rimbalzo compreso tra il 2% e il 5%.
• poor: tasso di rimbalzo pari o superiore al 5%. Controlla e ripulisci la lista di invio.

forwarding_bounces_excluded indica quanti rimbalzi legati all’inoltro sono stati esclusi dal calcolo dei tassi (in linea con la dashboard, che li considera anomalie di instradamento e non problemi della lista del mittente).

Elenco dei rimbalzi per destinatario

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Parametri della query

Elenco limitato alla casella

Per analizzare la reputazione di ogni mittente, limita la richiesta a una casella:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

La risposta ha la stessa struttura dell’endpoint del dominio.

Riservatezza delle risposte SMTP

TrekMail rimuove le informazioni diagnostiche interne prima di restituire una risposta SMTP. Il messaggio rimanente è lo stesso mostrato al proprietario dell’account nella dashboard e serve a diagnosticare i problemi di consegna, non a esporre informazioni interne del server.

Strumenti MCP

Tutti e tre gli strumenti accettano gli stessi parametri degli endpoint REST. Sono di sola lettura e non modificano la posta o le impostazioni dell’account.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

Intestazioni di recapitabilità per mittenti di grandi volumi

Se invii messaggi di marketing o posta collettiva in abbonamento, i principali provider di caselle potrebbero richiedere intestazioni per annullare l’iscrizione con un clic. Google applica questa regola ai messaggi di marketing e in abbonamento provenienti da mittenti che superano la sua soglia per i grandi volumi; la regola di annullamento con un clic non si applica ai messaggi transazionali. Esistono due modi per aggiungere le intestazioni:

Per messaggio (granulare). Passale tramite il campo headers di POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

Il campo headers accetta un elenco ristretto: List-Unsubscribe, List-Unsubscribe-Post, Reply-To e qualsiasi intestazione di tracciamento personalizzata X-*. L’iniezione di intestazioni (CR/LF) e le intestazioni gestite (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature e così via) vengono rifiutate con 422.

Per l’intero account (configurazione unica). Se ogni messaggio in uscita da questo account è automatizzato, puoi attivare auto_list_unsubscribe sull’account. Quando è attiva, la piattaforma aggiunge un’intestazione List-Unsubscribe con il solo indirizzo mailto a ogni messaggio in uscita che non ne abbia già una. Non aggiunge List-Unsubscribe-Post, quindi questo metodo di riserva non offre l’annullamento dell’iscrizione con un clic secondo RFC 8058. Per un annullamento con un clic conforme ai requisiti dei provider, fornisci entrambe le intestazioni per ogni messaggio usando un tuo endpoint HTTPS, come nell’esempio precedente. Le intestazioni fornite dal chiamante hanno sempre la precedenza. L’opzione è disattivata per impostazione predefinita e gli account esistenti non cambiano.

Per la posta personale individuale, lascia l’opzione disattivata. Quando questa intestazione è presente, Gmail potrebbe mostrare un pulsante Annulla iscrizione accanto al mittente, una scelta generalmente inappropriata per una conversazione.

Modelli per agenti IA

Questi endpoint consentono alcuni flussi particolarmente utili:

• Riepilogo settimanale della reputazione. Ogni lunedì, chiama get_domain_deliverability per ogni dominio dell’account e pubblica un riepilogo su Slack o Teams. Evidenzia solo i domini in cui status è warning o poor.
• Pulizia della lista basata sui rimbalzi. Chiama list_domain_bounces?type=hard&days=14, rimuovi i duplicati da recipient_email, quindi escludi quegli indirizzi dalla lista di invio. I rimbalzi hard indicano solitamente che l’indirizzo del destinatario non esiste più e ripetere l’invio spreca il margine di recapitabilità.
• Analisi per mittente. Quando il bounce_rate di una singola casella aumenta, chiama list_mailbox_bounces e raggruppa i risultati per smtp_status_code. Un’impennata di codici 550 può indicare che la lista degli indirizzi è obsoleta; un’impennata di codici 421 può indicare che il server di posta ricevente ha limitato la frequenza delle richieste.
• Indagine dell’assistenza clienti. Quando un utente segnala che un messaggio non è arrivato, chiedi all’agente di chiamare list_domain_bounces?recipient=<their-address>. La risposta SMTP può suggerire l’azione successiva, ad esempio liberare una casella del destinatario piena, rimuovere un blocco del destinatario o correggere un rifiuto DMARC.

Controllo delle versioni

Questi endpoint seguono lo stesso contratto di versionamento del resto dell’API v1: solo modifiche additive e nessuna rinomina incompatibile dei campi senza uno spazio dei nomi v2/.