Mailpro™ CRM API v3 : Riferimento

POST /token

Ottieni token di accesso

Ottiene un token JWT Bearer utilizzando le credenziali client. Passa l'access_token restituito come Authorization: Bearer <token> in tutte le richieste successive.

Tipi di concessione supportati

Durata del token

• Token di accesso: 30 giorni
• Refresh token: 90 giorni

Utilizza grant_type=refresh_token per ottenere un nuovo token di accesso senza autenticarsi di nuovo — il tuo SDK dovrebbe farlo automaticamente quando il token di accesso si avvicina alla scadenza (strategia tipica: rinnova quando rimangono meno di 24 h).

Conservazione sicura dei token

Anche con una durata di 30 giorni, chiunque ottenga un access_token può impersonare il tuo account fino alla scadenza. Conserva i token in un archivio segreto lato server (Vault, AWS Secrets Manager, Azure Key Vault, variabili d'ambiente su un host rinforzato). Mai incorporare un token in:

• JavaScript lato client o qualsiasi bundle del browser
• App mobili distribuite agli utenti finali (il binario può essere ispezionato)
• repository Git pubblici o log di build CI

Se un token viene divulgato, revocalo tramite le impostazioni del tuo account Mailpro e richiedine uno nuovo.

Corpo della richiesta (application/x-www-form-urlencoded)

Risposte

Esempio 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "userName": "12345",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "application": null
}

Esempio 400

{
  "error": "invalid_grant",
  "error_description": "The username or password is incorrect."
}

GET /Account/Me

Ottieni dettagli dell'account

Restituisce i dettagli del profilo e le impostazioni dell'account Mailpro autenticato.

Risposte

GET /Account/Credits

Ottieni saldo crediti

Restituisce il saldo dei crediti email e SMS rimanenti per l'account.

Risposte

Esempio 200

{
  "email_credits": 48500,
  "sms_credits": 1200
}

GET /Account/SubscriptionEndDate

Ottieni data di scadenza dell'abbonamento

Restituisce la data di scadenza dell'attuale abbonamento Mailpro.

Risposte

GET /Account/Limits

Ottieni quota API mensile

Restituisce la quota mensile di richieste API per il client autenticato.

Calcolo della quota: il limite è calibrato a partire dai crediti dell'abbonamento email (tipicamente subscription_credits × 5). Per un piano da 10.000 email/mese, ciò produce un budget mensile di 50.000 richieste. La mappatura esatta è impostata dal job di fatturazione alla registrazione dell'abbonamento e azzerata alla data di anniversario dell'abbonamento (non il 1° del mese di calendario).

Cosa consuma crediti:

• Ogni richiesta API autenticata agli endpoint v2, v3 o sms (ogni chiamata = 1 credito, indipendentemente dal risultato — sia le 2xx sia la maggior parte degli errori business 4xx vengono conteggiati).
• Ogni evento webhook inviato a un endpoint sottoscritto (es. contact.created inviato al tuo webhook sottoscritto = 1 credito oltre alla chiamata API che l'ha attivato).

Cosa è GRATUITO (non consuma crediti):

• Endpoint /health (monitoraggio).
• Richieste che falliscono con 401 (fallimento auth), 403 (vietato) o 429 (rate limit superato).
• Eventi webhook per client senza sottoscrizione corrispondente (cortocircuito tramite cache — nessun impatto sulla quota).

Risposte

POST /Contact

Crea un contatto

Crea un nuovo contatto CRM con campi personalizzati opzionali, assegnazioni a liste e tag.

Obbligatori:

• email — deve essere univoco nell'account
• lists — è obbligatoria almeno una assegnazione a una lista

I numeri di telefono accettano +41…, 0041… o 41… con o senza separatori (massimo 12 cifre su Contact — vedi Formato del numero di telefono nella descrizione dell'API).

I campi personalizzati sono identificati dal loro id (da GET /Field). I valori vengono validati rispetto al tipo del campo.

Scope OAuth : contacts:write

Corpo della richiesta (application/json)

Esempio

{
  "email": "[email protected]",
  "phone_number": "+41791234567",
  "lists": [
    {
      "id": 101
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ]
}

Risposte

Esempio 406

{
  "Message": "Contact cannot be created. A contact already exist with the same Email"
}

POST /Contact/Multiple

Importa contatti (in blocco)

Crea fino a 1.000 contatti in una singola richiesta per un'importazione in blocco efficiente. La risposta include un elenco dei contatti creati con successo e un elenco di errori per i contatti che non è stato possibile creare (es. email duplicata, dati non validi).

Nota: le liste e i tag utilizzati nelle importazioni in blocco non devono essere collegati ad alcun flusso di lavoro di automazione attivo. In tal caso, l'intera importazione viene rifiutata con HTTP 406.

Scope OAuth : contacts:write

Corpo della richiesta (application/json)

Esempio

[
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Alice"
      }
    ]
  },
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Bob"
      }
    ]
  }
]

Risposte

Esempio 200

{
  "Added": [
    {
      "Email": "[email protected]",
      "Id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "Email": "[email protected]",
      "Id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "Errors": []
}

GET /Contact/{id}

Ottieni un contatto

Restituisce i dettagli di un contatto specifico. Utilizza includeTags=true per restituire anche i tag assegnati al contatto. Utilizza includeLists=true per restituire anche le liste a cui appartiene il contatto.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone_number": "41791234567",
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "lists": [
    {
      "id": 101
    }
  ]
}

PUT /Contact/{id}

Aggiorna un contatto

Aggiorna l'email, il numero di telefono, i campi personalizzati, le assegnazioni a liste e i tag di un contatto. Il corpo della richiesta sostituisce i dati correnti del contatto — includi tutte le liste e i tag a cui vuoi che il contatto rimanga assegnato.

Obbligatori nel corpo: email e almeno una voce lists.

Scope OAuth : contacts:write

Parametri

Corpo della richiesta (application/json)

Risposte

Esempio 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Elimina un contatto

Elimina definitivamente un contatto dal CRM.

Scope OAuth : contacts:write

Parametri

Risposte

GET /Contact/{id}/Activity

Attività di un contatto su 90 giorni

Email ricevute, aperte e cliccate, client di posta preferito e ultime campagne del contatto.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

{
  "period_days": 90,
  "email_received": 12,
  "email_opened": 7,
  "email_clicked": 2,
  "favorite_email_client": "Gmail",
  "last_campaigns": [
    {
      "id": 5001,
      "name": "Spring Sale 2026",
      "date": "2026-10-01T09:00:00"
    }
  ]
}

PUT /Contact/{id}/Tag/{tagid}

Aggiungi tag al contatto

Assegna un tag a un contatto. Se il tag è già assegnato, l'operazione è inefficace.

Scope OAuth : contacts:write

Parametri

Risposte

DELETE /Contact/{id}/Tag/{tagid}

Rimuovi tag dal contatto

Rimuove l'assegnazione di un tag da un contatto.

Scope OAuth : contacts:write

Parametri

Risposte

PUT /Contact/{id}/List/{listid}

Aggiungi contatto alla lista

Aggiunge un contatto a una lista specifica. Restituisce HTTP 404 se il contatto era precedentemente disiscritto da questa lista.

Scope OAuth : contacts:write

Parametri

Risposte

DELETE /Contact/{id}/List/{listid}

Rimuovi contatto dalla lista

Rimuove un contatto da una lista specifica. Il contatto stesso non viene eliminato.

Scope OAuth : contacts:write

Parametri

Risposte

GET /List

Elenca le liste di contatti

Restituisce tutte le liste di contatti per l'account. Filtra per nome o data di creazione. Ordina alfabeticamente con sortByName=true. Includi il conteggio totale dei contatti per lista con includeTotalContacts=true.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

[
  {
    "id": 101,
    "name": "Newsletter subscribers",
    "total_contacts": 4521,
    "date_creation": "2025-01-15T10:30:00"
  }
]

POST /List

Crea una lista di contatti

Crea una nuova lista di contatti. Massimo 1.000 liste per account.

Scope OAuth : contacts:write

Corpo della richiesta (application/json)

Esempio

{
  "name": "Spring Campaign 2026"
}

Risposte

Esempio 200

{
  "id": 102,
  "name": "Spring Campaign 2026",
  "date_creation": "2026-04-14T12:00:00"
}

GET /List/{id}

Ottieni una lista di contatti

Restituisce i dettagli di una lista di contatti specifica.

Scope OAuth : contacts:read

Parametri

Risposte

PUT /List/{id}

Aggiorna una lista di contatti

Rinomina una lista di contatti esistente.

Scope OAuth : contacts:write

Parametri

Corpo della richiesta (application/json)

Esempio

{
  "name": "Newsletter subscribers — Europe"
}

Risposte

DELETE /List/{id}

Elimina una lista di contatti

Elimina definitivamente una lista di contatti. I contatti stessi non vengono eliminati — viene rimossa solo la loro appartenenza a questa lista. Le liste utilizzate da flussi di lavoro di automazione attivi non possono essere eliminate.

Scope OAuth : contacts:write

Parametri

Risposte

GET /List/{id}/Contact

Elenca i contatti in una lista

Restituisce i contatti appartenenti a una lista specifica. Filtra per email o data di aggiunta. Includi i tag e le appartenenze alle liste con i flag corrispondenti.

Scope OAuth : contacts:read

Parametri

Risposte

GET /List/{listId}/Unsubscribers

Elenca i disiscritti

Restituisce i contatti che si sono disiscritti da una lista specifica.

Scope OAuth : contacts:read

Parametri

Risposte

GET /Tag

Elenca i tag

Restituisce tutti i tag per l'account.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

[
  {
    "id": 5,
    "name": "VIP customers"
  },
  {
    "id": 6,
    "name": "Newsletter openers"
  }
]

POST /Tag

Crea un tag

Crea un nuovo tag. Massimo 1.000 tag per account.

Scope OAuth : contacts:write

Corpo della richiesta (application/json)

Esempio

{
  "name": "VIP customers"
}

Risposte

GET /Tag/{id}

Ottieni un tag

Restituisce un tag specifico tramite il suo ID.

Scope OAuth : contacts:read

Parametri

Risposte

PUT /Tag/{id}

Aggiorna un tag

Rinomina un tag esistente.

Scope OAuth : contacts:write

Parametri

Corpo della richiesta (application/json)

Esempio

{
  "name": "VIP customers — updated"
}

Risposte

DELETE /Tag/{id}

Elimina un tag

Elimina definitivamente un tag. Il tag viene rimosso da tutti i contatti. I tag utilizzati da flussi di lavoro di automazione attivi non possono essere eliminati.

Scope OAuth : contacts:write

Parametri

Risposte

GET /Tag/{id}/Contact

Elenca i contatti con un tag

Restituisce i contatti a cui è stato assegnato un tag specifico.

Scope OAuth : contacts:read

Parametri

Risposte

GET /Field

Elenca i campi personalizzati

Restituisce tutti i campi personalizzati dei contatti definiti per l'account. Utilizza i valori id restituiti durante la creazione o l'aggiornamento dei contatti.

Parametri

Risposte

Esempio 200

[
  {
    "id": 1,
    "name": "first_name",
    "personalisation_key": "first_name",
    "field_type": "text"
  },
  {
    "id": 2,
    "name": "last_name",
    "personalisation_key": "last_name",
    "field_type": "text"
  }
]

POST /Field

Crea un campo personalizzato

Crea un nuovo campo personalizzato per i contatti. Massimo 50 campi per account. Utilizza l'id restituito quando assegni valori ai contatti.

Corpo della richiesta (application/json)

Esempio

{
  "name": "First name",
  "id_field_type": 1,
  "personalize_key": "first_name"
}

Risposte

GET /Field/Types

Elenca i tipi di campo

Restituisce gli identificatori dei tipi di campo disponibili da utilizzare durante la creazione di un campo personalizzato. Tipi comuni: 1 = text, 2 = number, 3 = date.

Risposte

GET /Field/{id}

Ottieni un campo personalizzato

Restituisce la definizione e i metadati di un campo personalizzato specifico.

Parametri

Risposte

PUT /Field/{id}

Aggiorna un campo personalizzato

Aggiorna il nome o la chiave di personalizzazione di un campo personalizzato.

Parametri

Corpo della richiesta (application/json)

Risposte

DELETE /Field/{id}

Elimina un campo personalizzato

Elimina definitivamente un campo personalizzato e rimuove il suo valore da tutti i contatti. Questa azione non può essere annullata.

Parametri

Risposte

GET /Campaign

Elenca le campagne

Restituisce un elenco paginato delle campagne email per l'account.

Parametri

Risposte

Esempio 200

[
  {
    "id": 8001,
    "title": "Spring Newsletter April 2026",
    "date_planned": "2026-04-20T09:00:01",
    "count_open": 1823,
    "count_sent": 4521,
    "count_click": 342,
    "count_badmail": 12,
    "count_unsubscription": 8,
    "count_clicking_users": 289,
    "count_complaints": 1,
    "spam_trap": 0,
    "deliverability_score": 98
  }
]

GET /Campaign/{id}

Ottieni una campagna

Restituisce la configurazione e il riepilogo delle statistiche di una campagna specifica.

Parametri

Risposte

PUT /Campaign/{id}

Aggiorna una campagna

Aggiorna il titolo o la data di invio di una campagna programmata. Le campagne possono essere modificate solo fino a 5 minuti prima dell'orario di invio programmato.

Parametri

Corpo della richiesta (application/json)

Risposte

DELETE /Campaign/{id}

Elimina una campagna

Annulla ed elimina definitivamente una campagna tramite il suo identificatore.

Parametri

Risposte

GET /Campaign/Scheduled

Elenca le mie campagne programmate

Restituisce le campagne con date_planned nel futuro che non sono ancora state inviate. Ordinate per date_planned crescente.

Parametri

Risposte

Esempio 200

[
  {
    "id": 5001,
    "id_client": 12345,
    "subject": "Spring Sale 2026",
    "date_planned": "2026-05-01T09:00:00",
    "title": "Spring Sale",
    "id_campaign": 7001,
    "id_list": 101,
    "id_segment": null,
    "number_email": 1250
  }
]

POST /Campaign/{id}/Cancel

Annulla una campagna programmata

Annulla una campagna programmata nel futuro. Restituisce 409 Conflict se la campagna è già stata inviata o non esiste.

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "cancelled": 5001
}

PATCH /Campaign/{id}/Reschedule

Riprogramma una campagna programmata

Aggiorna la data di invio pianificata di una campagna programmata. La nuova data deve essere nel futuro ed entro 90 giorni.

Nome del campo nel corpo: l'API accetta date_planned (snake_case, primario) nonché gli alias legacy PlanDate e scheduled_time. Fornisci uno qualsiasi di essi — viene utilizzato il primo non-null.

Parametri

Corpo della richiesta (application/json)

Risposte

Esempio 200

{
  "result": "ok",
  "id": 5001,
  "date_planned": "2026-12-31T14:30:00"
}

GET /Campaign/{id}/ByHour

Statistiche per ora

Restituisce la suddivisione oraria di aperture e clic per la campagna.

Parametri

Risposte

GET /Campaign/{id}/ByDay

Statistiche per giorno

Restituisce la suddivisione giornaliera di aperture e clic per la campagna.

Parametri

Risposte

GET /Campaign/{id}/Openings

Elenca le aperture email

Restituisce un elenco paginato dei contatti che hanno aperto l'email della campagna.

Parametri

Risposte

GET /Campaign/{id}/Clicks

Elenca i clic sui link

Restituisce un elenco paginato dei contatti che hanno cliccato un link nella campagna.

Parametri

Risposte

GET /Campaign/{id}/HardBounces

Elenca gli hard bounce

Restituisce gli indirizzi email che hanno subito hard bounce durante questa campagna.

Parametri

Risposte

GET /Campaign/{id}/Links

Elenca i link tracciati

Restituisce i dati sulle prestazioni dei clic per ogni link tracciato nella campagna.

Parametri

Risposte

GET /Campaign/{id}/OS

Statistiche per OS / dispositivo

Restituisce la suddivisione di aperture e clic per sistema operativo e tipo di dispositivo.

Parametri

Risposte

GET /Campaign/{id}/EmailClients

Statistiche per client email

Restituisce la suddivisione delle aperture per client email (Gmail, Outlook, Apple Mail…).

Parametri

Risposte

GET /Campaign/{id}/Countries

Statistiche per paese

Restituisce la distribuzione geografica di aperture e clic.

Parametri

Risposte

POST /Send/Mail

Invia email transazionale

Invia un'email transazionale una tantum a un singolo destinatario.

Destinatario: fornisci email (indirizzo inline) O id_contact (contatto CRM) — non entrambi. L'uso di id_contact abilita la personalizzazione automatica con i valori dei campi personalizzati del contatto.

Contenuto: fornisci body_html (HTML inline) O id_message (modello salvato) — non entrambi. Se sono forniti entrambi, id_message ha la precedenza.

Obbligatori: id_sender_email, subject e uno tra (email o id_contact), e uno tra (body_html o id_message).

Corpo della richiesta (application/json)

Esempio

{
  "id_sender_email": 201,
  "email": "[email protected]",
  "subject": "Your order #12345 has shipped",
  "body_html": "<p>Hello {{first_name}}, your order is on its way!</p>",
  "reply_to": "[email protected]",
  "fields": [
    {
      "id": 1,
      "value": "Alice"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJVBERi0xLjQK..."
    }
  ]
}

Risposte

Esempio 200

{
  "message": "Successful operation",
  "id_single_send": 8001
}

Esempio 404

{
  "Message": "Not enough credit available"
}

GET /Send/{id}/Status

Ottieni lo stato di consegna di un'email transazionale

Restituisce lo stato di consegna attuale di un'email transazionale inviata con POST /Send/Mail. Passa l'id_single_send restituito da quella chiamata.

Valori possibili: delivered (accettata dal server del destinatario, vedi diag_code), bounced (rifiutata — bounce_type: hard indirizzo non valido o rifiuto definitivo, soft rifiuto dopo nuovi tentativi), sent (consegnata al server di posta, ancora nessuna risposta), scheduled (non ancora inviata, date_planned nel futuro) e queued (in attesa di invio). delivered e bounced sono finali: smettete di interrogare. Ogni email ha uno stato finale al più tardi 48 ore dopo l'invio; interrogate al massimo ogni 15 minuti (ogni chiamata conta nella vostra quota API) oppure usate i webhook email.delivered / email.bounced. Solo il cliente che ha inviato l'email può leggerne lo stato — qualsiasi altro id restituisce 404.

Parametri

Risposte

Esempio 200

{
  "id_single_send": 8001,
  "email": "[email protected]",
  "status": "delivered",
  "date_planned": "2026-04-15T14:30:00",
  "status_date": "2026-04-15T14:30:07",
  "diag_code": "2.0.0 (success)",
  "bounce_type": null
}

POST /Send/Campaign

Invia campagna email

Invia una campagna email in blocco a una o più liste di contatti.

Obbligatori:

• id_message — il modello da inviare (da GET /Message)
• id_sender_email — l'indirizzo del mittente (da GET /SenderEmail)
• lists — almeno una lista di contatti target
• campaign_title — etichetta per il tracciamento delle statistiche

Segmento: opzionalmente filtra i destinatari tramite un segmento salvato (id_segment). Il segmento filtra i contatti all'interno delle liste specificate.

Programmazione: imposta date_planned a una data/ora ISO 8601 futura. Le campagne possono essere modificate o annullate fino a 5 minuti prima dell'orario programmato.

Corpo della richiesta (application/json)

Esempio

{
  "id_message": 501,
  "id_sender_email": 201,
  "lists": [
    {
      "id": 101
    }
  ],
  "campaign_title": "Spring Newsletter April 2026",
  "date_planned": "2026-04-20T09:00:00"
}

Risposte

Esempio 200

{
  "Message": "Successful operation. Campaigns can be edited or deleted until 5 minutes prior to send.",
  "IdCampaign": 8001
}

GET /Send

Elenca gli invii programmati

Restituisce l'elenco delle campagne email in attesa di essere inviate (programmate, non ancora elaborate).

Parametri

Risposte

DELETE /Send/{id}

Annulla un invio programmato

Annulla ed elimina un invio email programmato che non è ancora stato elaborato. Non è possibile annullare gli invii attualmente in fase di elaborazione.

Parametri

Risposte

GET /Send/Mail/Scheduled

Elenca le email singole pianificate

Restituisce le email singole inviate con POST /Send/Mail e una data futura, non ancora partite. Le campagne sono elencate da GET /Campaign/Scheduled.

Scope OAuth : email:send

Risposte

Esempio 200

[
  {
    "id_single_send": 880123,
    "email": "[email protected]",
    "subject": "Your invoice",
    "date_planned": "2026-12-01T09:00:00"
  }
]

POST /Send/Mail/{id}/Cancel

Annulla un'email singola pianificata

Annulla l'email finché non è partita.

Scope OAuth : email:send

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "cancelled": 880123
}

PATCH /Send/Mail/{id}/Reschedule

Ripianifica un'email singola pianificata

Cambia la data di invio. La nuova data deve essere futura ed entro 90 giorni. È accettato anche POST.

Scope OAuth : email:send

Parametri

Corpo della richiesta (application/json)

Risposte

Esempio 200

{
  "result": "ok",
  "id": 880123,
  "date_planned": "2026-12-15T09:00:00"
}

GET /SenderEmail

Elenca gli indirizzi mittente

Restituisce gli indirizzi email mittenti validati configurati per l'account.

Parametri

Risposte

Esempio 200

[
  {
    "id": 201,
    "email": "[email protected]",
    "sender_name": "Your Company Newsletter",
    "is_validated": true
  }
]

POST /SenderEmail

Aggiungi un indirizzo mittente

Aggiunge l'indirizzo con gli stessi controlli dell'applicazione e gli invia un'email di convalida. È utilizzabile dopo aver cliccato il link in quell'email. Un account può avere fino a 25 mittenti, convalidati o in attesa.

Scope OAuth : email:templates:write

Corpo della richiesta (application/json)

Risposte

Esempio 200

{
  "result": "ok",
  "confirmation_sent": true,
  "domain_has_mx": true
}

POST /SenderEmail/{id}/ResendValidation

Invia di nuovo l'email di convalida

Per un indirizzo ancora in attesa di convalida.

Scope OAuth : email:templates:write

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "confirmation_sent": true
}

GET /SenderEmail/{id}/Authentication

Controlla il dominio di un mittente (SPF, DKIM, DMARC, MX)

Controlla il dominio in tempo reale nel DNS e restituisce i record da pubblicare. Sola lettura. Il DKIM si attiva nell'applicazione: dkim_settings_url apre la schermata giusta.

Scope OAuth : email:templates:read

Parametri

Risposte

Esempio 200

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:spf.mailpro.com -all",
    "recommended_record": "v=spf1 include:spf.mailpro.com -all",
    "change_needed": false
  },
  "dkim": {
    "valid": true,
    "records": [
      {
        "host": "key._domainkey.example.com",
        "value": "v=DKIM1;k=rsa;p=MIIBIjANBgkq...",
        "validated": true
      }
    ]
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=quarantine"
  },
  "mx": {
    "valid": true,
    "record": "mail.example.com"
  },
  "dkim_settings_url": "https://app.mailpro.com/dkim/list?d=example.com"
}

GET /History/Email

Elenca lo storico degli invii email

Restituisce il registro degli invii email passati per l'account.

Parametri

Risposte

GET /History/SMS

Elenca lo storico degli invii SMS

Restituisce il registro degli invii SMS passati per l'account.

Parametri

Risposte

GET /Segment

Elenca i segmenti

Restituisce tutti i segmenti dinamici salvati per l'account.

Scope OAuth : contacts:read

Parametri

Risposte

GET /Segment/{id}/Contact

Elenca i contatti di un segmento

Con id_list, restituisce solo i contatti di quella lista presenti nel segmento: quelli che una campagna lista + segmento raggiungerebbe. Il totale è nell'intestazione X-Total-Count.

Scope OAuth : contacts:read

Parametri

Risposte

GET /Segment/{id}/Count

Conta i contatti di un segmento

Solo il numero, per conoscere in anticipo la dimensione di un invio. Con id_list, conta solo i contatti di quella lista presenti nel segmento.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

{
  "total": 1250
}

GET /Segment/{id}/contact/{contactId}/check

Verifica se un contatto corrisponde a un segmento

Verifica se un contatto specifico (tramite GUID) corrisponde attualmente alle regole di un determinato segmento. Utile per attivare la logica di automazione su richiesta.

Scope OAuth : contacts:read

Parametri

Risposte

POST /Sms/SingleSMS

Invia singolo SMS

Invia un singolo SMS direttamente a un numero di telefono. Utilizzalo per messaggi transazionali (OTP, conferme d'ordine, avvisi). Il numero di telefono accetta +41…, 0041… o 41… con o senza separatori — vedi Formato del numero di telefono nella descrizione dell'API per gli input accettati / rifiutati.

Corpo della richiesta (application/json)

Esempio

{
  "phone_number": "+41791234567",
  "message": "Your verification code is 9473. Valid for 10 minutes."
}

Risposte

POST /Sms/Campaign

Invia campagna SMS

Invia un messaggio SMS al campo phone_number di tutti i contatti in una o più liste. I contatti senza un numero di telefono vengono saltati.

Corpo della richiesta (application/json)

Esempio

{
  "lists": [
    {
      "id": 101
    }
  ],
  "message": "Flash sale today — 20% off. Shop at mailpro.com",
  "date_planned": "2026-04-20T10:00:00"
}

Risposte

GET /Sms

Elenca lo storico SMS

Restituisce il registro degli invii SMS (sia singoli che di campagna) per l'account.

Parametri

Risposte

DELETE /Sms/{id}

Annulla un SMS programmato

Annulla un invio SMS programmato in attesa.

Parametri

Risposte

GET /Sms/Scheduled

Elenca gli invii SMS programmati

Restituisce gli invii SMS con una date_planned futura (non ancora inviati), ordinati per data crescente.

Parametri

Risposte

POST /Sms/{id}/Cancel

Annulla un SMS programmato

Annulla un invio SMS programmato solo se non è ancora stato inviato.

Parametri

Risposte

PATCH /Sms/{id}/Reschedule

Riprogramma un SMS programmato

Aggiorna la data di invio pianificata di un SMS programmato. La nuova data deve essere nel futuro ed entro 90 giorni. Fallisce se l'SMS è già stato inviato.

Nome del campo nel corpo: l'API accetta date_planned (snake_case, primario) nonché gli alias legacy PlanDate e scheduled_time. Fornisci uno qualsiasi di essi.

Parametri

Corpo della richiesta (application/json)

Risposte

GET /FolderList

Elenca le cartelle delle liste

Restituisce le cartelle utilizzate per organizzare le liste di contatti.

Parametri

Risposte

GET /FolderList/{id}

Ottieni una singola cartella di liste

Restituisce i dettagli di una cartella di liste tramite il suo ID.

Parametri

Risposte

GET /FolderMessage

Elenca le cartelle dei messaggi

Restituisce le cartelle utilizzate per organizzare i modelli di messaggi email.

Parametri

Risposte

POST /Import/Upload

Carica un file di contatti (CSV / XLSX) per l'importazione in blocco

Carica un file CSV o XLSX per importare contatti in una lista. Il file viene memorizzato e messo in coda per l'elaborazione asincrona — l'endpoint restituisce immediatamente un import_job_id.

Tipo di richiesta: multipart/form-data

Campi del modulo obbligatori:

• id_list (intero) — ID della lista di destinazione
• file (binario) — il file CSV o XLSX da caricare
• json_match_fields (stringa, JSON) — quale colonna del file va in quale campo del contatto. email_position = colonna dell'e-mail, numerata da 0 (obbligatorio), phone_position = colonna del numero di cellulare o -1, fields = ID degli altri campi (vedi GET /Field), fields_position = colonna di ciascuno di essi, update_fields = aggiornare i contatti esistenti. Corrispondenza assente o non valida: risposta 400, nessuna importazione viene creata.

Opzionali:

• webhook_url (stringa) — URL HTTPS chiamato al termine dell'elaborazione. Riceve un payload JSON con lo stato finale (success / failed) e i conteggi delle righe importate / saltate / non valide.

Formato del file:

• Codifica UTF-8
• La prima riga può contenere le intestazioni (rilevamento automatico: una prima riga senza alcun indirizzo e-mail viene ignorata)
• Le colonne sono associate ai campi tramite json_match_fields
• Dimensione massima del file: 50 MB

Corpo della richiesta (multipart/form-data)

Risposte

Esempio 200

{
  "result": "OK",
  "import_job_id": 14,
  "internal_name": "230575-20260420142615-contacts.csv"
}

GET /Webhook

Elenca i webhook

Restituisce ogni webhook configurato sull'account autenticato.

Risposte

POST /Webhook

Crea un webhook

Crea una nuova sottoscrizione webhook. La risposta contiene un secret che viene mostrato solo una volta — memorizzalo immediatamente, lato server. Utilizzalo per verificare la firma HMAC di ogni payload in arrivo.

Limiti: massimo 20 webhook per account, massimo 50 eventi per webhook.

Corpo della richiesta (application/json)

Esempio

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Integrazione Slack"
}

Risposte

Esempio 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Integrazione Slack",
  "isActive": true,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "autoDisabledReason": null,
  "createdAt": "2026-05-25T10:00:00Z",
  "updatedAt": "2026-05-25T10:00:00Z",
  "secret": "whsec_AbcD1234EfgH5678IjkL9012MnoP3456QrsT"
}

GET /Webhook/{id}

Ottieni un webhook

Parametri

Risposte

PUT /Webhook/{id}

Aggiorna un webhook

Aggiornamento parziale — vengono modificati solo i campi inviati.

Parametri

Corpo della richiesta (application/json)

Risposte

DELETE /Webhook/{id}

Elimina un webhook

Elimina definitivamente il webhook e l'intero storico delle consegne.

Parametri

Risposte

POST /Webhook/{id}/test

Invia un evento di test

Mette in coda un evento ping immediato (o qualsiasi altro tipo di evento tramite il campo eventType nel corpo) verso il tuo endpoint. Utile per verificare la raggiungibilità e la verifica della firma prima di affidarsi agli eventi reali.

Parametri

Corpo della richiesta (application/json)

Esempio

{
  "eventType": "ping"
}

Risposte

Esempio 202

{
  "deliveryId": 1234,
  "eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
  "eventType": "ping"
}

POST /Webhook/{id}/rotate-secret

Ruota il secret HMAC

Genera un nuovo secret HMAC e invalida immediatamente quello vecchio. Il nuovo secret viene restituito una sola volta nella risposta — memorizzalo. Ogni consegna da questo momento in poi sarà firmata con il nuovo secret.

Utilizzalo se sospetti che il tuo secret sia stato compromesso.

Parametri

Risposte

Esempio 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /Webhook/{id}/deliveries

Elenca i tentativi di consegna

Restituisce lo storico dei tentativi di spedizione per questo webhook (retention di 30 giorni). Utile per il debug — quali eventi sono stati inviati, codici di stato ricevuti, numero di tentativi, messaggi di errore.

Parametri

Risposte

POST /Webhook/{id}/deliveries/{deliveryId}/replay

Rinvia una consegna

Mette in coda un nuovo tentativo di consegna con lo stesso payload dell'originale. Utile per riattivare una consegna fallita dopo aver corretto il tuo endpoint. Viene creata una NUOVA riga Webhook_Delivery (l'originale viene preservata per audit). Il replay segue la politica di retry standard (10s → 1min → 5min → 30min → 2h → 6h → 24h, poi abbandonato).

Parametri

Risposte

GET /Suppression/Bounces

Elenca i bounce dell'account

Prima i più recenti. Il totale è nell'intestazione X-Total-Count.

Scope OAuth : email:read

Parametri

Risposte

Esempio 200

[
  {
    "id": 5521,
    "source": "contact",
    "type": "hard",
    "email": "[email protected]",
    "date": "2026-10-12T08:30:00",
    "diag_code": "550 5.1.1 User unknown",
    "id_list": 101
  }
]

DELETE /Suppression/Bounces/{id}

Rimuovi un bounce

source e type sono obbligatori, come restituiti da GET /Suppression/Bounces: un id da solo non è univoco.

Scope OAuth : contacts:write

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "id": 5521,
  "restored": false
}

POST /Suppression/Bounces/{id}/Restore

Rimetti nelle sue liste un contatto in hard bounce

Solo per un hard bounce con origine contact.

Scope OAuth : contacts:write

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "id": 5521,
  "restored": true
}

GET /Suppression/Unsubscribers

Elenca i disiscritti dell'account

Prima i più recenti. Il totale è nell'intestazione X-Total-Count.

Scope OAuth : contacts:read

Parametri

Risposte

Esempio 200

[
  {
    "id": 9012,
    "source": "api3",
    "email": "[email protected]",
    "date": "2026-10-20T16:05:00",
    "list_name": null,
    "comment": "Asked by phone"
  }
]

POST /Suppression/Unsubscribers

Aggiungi un disiscritto

Senza id_list, l'indirizzo viene disiscritto per tutto l'account. Con id_list, solo da quella lista di disiscrizione.

Scope OAuth : contacts:write

Corpo della richiesta (application/json)

Risposte

Esempio 200

{
  "result": "ok",
  "already_unsubscribed": false
}

DELETE /Suppression/Unsubscribers/{id}

Rimuovi un disiscritto

source è obbligatorio, come restituito da GET /Suppression/Unsubscribers: un id da solo non è univoco.

Scope OAuth : contacts:write

Parametri

Risposte

Esempio 200

{
  "result": "ok",
  "removed": 9012
}