Guida Email

UniMsg permette di inviare email transazionali e di marketing con alta deliverability e tracking avanzato.

Caratteristiche

• Invio email transazionali e marketing
• Supporto HTML e testo puro
• Allegati fino a 25MB
• Tracking aperture e click
• Gestione bounce e unsubscribe
• Costo: 0.5 crediti per email

Endpoint

Metodo	Endpoint	Descrizione
POST	/v1/email/send	Invia email
POST	/v1/email/bulk	Invio massivo
GET	/v1/email/{id}	Stato email
GET	/v1/email/{id}/events	Eventi (aperture, click)

Invio Email Semplice

Richiesta

POST /v1/email/send
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "to": "test@example.com",
    "from": "noreply@mycompany.com",
    "from_name": "My Company",
    "subject": "Conferma ordine #12345",
    "html": "<h1>Grazie per il tuo ordine!</h1><p>Il tuo ordine è stato ricevuto.</p>",
    "text": "Grazie per il tuo ordine! Il tuo ordine è stato ricevuto."
}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
to	string|array	Sì	Destinatario/i
from	string	Sì	Indirizzo mittente
from_name	string	No	Nome visualizzato mittente
subject	string	Sì	Oggetto email
html	string	No*	Contenuto HTML
text	string	No*	Contenuto testo puro
cc	string|array	No	Copia carbone
bcc	string|array	No	Copia carbone nascosta
reply_to	string	No	Indirizzo per risposte
attachments	array	No	Allegati
track_opens	boolean	No	Traccia aperture (default: true)
track_clicks	boolean	No	Traccia click (default: true)

* Almeno uno tra html e text è obbligatorio.

Risposta

{
    "success": true,
    "data": {
        "message_id": "msg_email_xxxxxxxxxxxx",
        "to": ["test@example.com"],
        "status": "queued",
        "credits_used": 0.5,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Email con Allegati

Puoi allegare file codificati in base64:

{
    "to": "test@example.com",
    "from": "noreply@mycompany.com",
    "subject": "La tua fattura",
    "html": "<p>In allegato la fattura richiesta.</p>",
    "attachments": [
        {
            "filename": "fattura.pdf",
            "content": "JVBERi0xLjQKJeLjz9MK...",
            "content_type": "application/pdf"
        }
    ]
}

Limiti Allegati

• Dimensione massima totale: 25 MB
• Numero massimo allegati: 10
• Contenuto deve essere in base64

Destinatari Multipli

Puoi inviare a più destinatari in una sola richiesta:

{
    "to": [
        "user1@example.com",
        "user2@example.com"
    ],
    "cc": ["manager@example.com"],
    "bcc": ["archive@example.com"],
    "from": "noreply@mycompany.com",
    "subject": "Newsletter Gennaio",
    "html": "<h1>Le novità del mese</h1>..."
}

Tracking Eventi

UniMsg traccia automaticamente aperture e click (disattivabile). Per vedere gli eventi:

GET /v1/email/msg_email_xxxxxxxxxxxx/events
Authorization: Bearer YOUR_ACCESS_TOKEN

Risposta:

{
    "success": true,
    "data": {
        "events": [
            {
                "type": "delivered",
                "timestamp": "2024-01-15T10:30:01Z"
            },
            {
                "type": "opened",
                "timestamp": "2024-01-15T10:35:00Z",
                "ip": "93.xxx.xxx.xxx",
                "user_agent": "Mozilla/5.0..."
            },
            {
                "type": "clicked",
                "timestamp": "2024-01-15T10:36:00Z",
                "url": "https://mycompany.com/promo"
            }
        ]
    }
}

Tipi di Eventi

Evento	Descrizione
queued	Email in coda
sent	Inviata al server destinatario
delivered	Accettata dal server
opened	Email aperta
clicked	Link cliccato
bounced	Rimbalzo (indirizzo non valido)
complained	Segnalata come spam
unsubscribed	Utente disiscritto

Configurazione Dominio

Per migliorare la deliverability, configura i record DNS del tuo dominio:

Record SPF

v=spf1 include:spf.unimsg.app ~all

Record DKIM

Il record DKIM ti verrà fornito nella dashboard dopo la verifica del dominio.

Record DMARC

v=DMARC1; p=quarantine; rua=mailto:dmarc@mycompany.com

Errori Comuni

Codice	Descrizione	Soluzione
INVALID_EMAIL	Formato email non valido	Verifica l'indirizzo
DOMAIN_NOT_VERIFIED	Dominio mittente non verificato	Configura i DNS
ATTACHMENT_TOO_LARGE	Allegati troppo grandi	Max 25MB totali
BLACKLISTED	Destinatario in blacklist	L'utente si è disiscritto