API SMS Mailpro™ : Riferimento

POST /token

Ottieni l'access token (redirect 307 verso /v3/token)

Ottiene un token JWT Bearer usando le credenziali client Mailpro. Passa l'access_token restituito come Authorization: Bearer <token> in tutte le richieste successive. Lo stesso token è valido anche sulle API CRM v3 e Email v2.

> ⚙ Dettaglio implementativo — POST /sms/token è un 307 Temporary > Redirect verso POST /v3/token (configurato a livello di rewrite IIS in > web.config). HTTP 307 preserva sia il metodo (POST) sia il > body della richiesta, quindi qualsiasi client HTTP conforme agli standard segue > il redirect in modo trasparente — continui a fare POST verso /sms/token e ottieni > un JWT valido. Non c'è alcuna logica di emissione token duplicata; l'API > SMS non emette mai token in proprio.

Tipi di grant supportati

Durata del token

• Access token: 30 giorni
• Refresh token: 90 giorni

Usa grant_type=refresh_token per rinnovare l'access token senza ri-autenticarti. Conserva i token lato server (Vault, variabili d'ambiente); non incorporarli mai nel JS del browser o nei binari delle app mobile. Consulta la nota di sicurezza completa nella documentazione /token dell'API CRM v3.

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/limits.{format}

Ottieni la quota API mensile

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

Calcolo della quota: il limite è calibrato sui crediti dell'abbonamento email (tipicamente subscription_credits × 5). Per un piano da 10.000 email/mese, questo produce un budget mensile di 50.000 richieste. Reset 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 evento webhook inviato a un endpoint sottoscritto.

Cosa è GRATUITO (non consuma crediti):

• Endpoint /health.
• Richieste che falliscono con 401, 403 o 429.
• Eventi webhook per client senza sottoscrizione corrispondente.

La quota è condivisa tra tutte e 3 le API Mailpro (v2, v3, sms) — un client = un budget mensile sull'intera piattaforma. Gli invii SMS consumano in aggiunta il saldo crediti SMS dedicato (GET /credit/get.{format}).

Scope OAuth : account:read

Parametri

Risposte

Esempio 200

{
  "monthlyLimit": 50000,
  "remaining": 32847,
  "used": 17153,
  "isFree": false,
  "remainedSendsForFree": null
}

POST /send/add.{format}

Invia SMS bulk a una lista di contatti

Invia un messaggio SMS a tutti i numeri di telefono in una lista di contatti. Supporta la pianificazione: imposta scheduled_time su una data futura per inviare in seguito, oppure ometterlo per inviare immediatamente.

Consumo dei crediti: i crediti vengono detratti al momento dell'invio. I messaggi lunghi (>160 caratteri GSM-7) vengono suddivisi in più parti, ciascuna delle quali costa crediti aggiuntivi.

La risposta restituisce { "Error": "Insufficient Credit", "Code": 202 } se l'account ha crediti insufficienti.

Scope OAuth : sms:send

Parametri

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

Risposte

Esempio 200

{
  "Id": 6001,
  "Message": "Flash sale today only — 30% off all orders. Shop now at mailpro.com/shop",
  "ScheduledTime": "2026-04-20T10:00:00",
  "To": [
    "42"
  ]
}

Esempio 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Esempio 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/add_single.{format}

Invia un singolo SMS (GET)

Invia un singolo SMS a un destinatario tramite una richiesta GET. Utile per integrazioni semplici dove POST non è disponibile. Credenziali e messaggio vengono passati come parametri della query string.

Nota: evita di usare GET per messaggi sensibili — i parametri della query appaiono nei log del server. Preferisci invece POST /send/add_single.

Scope OAuth : sms:send

Parametri

Risposte

Esempio 200

{
  "Id": 5001,
  "Message": "Your appointment is confirmed for tomorrow at 10:00.",
  "ScheduledTime": "2026-04-15T09:00:00",
  "To": "0041791234567",
  "Charge": "1"
}

POST /send/add_single.{format}

Invia un singolo SMS

Invia un singolo messaggio SMS a un numero di telefono destinatario. Supporta la pianificazione tramite scheduled_time.

Consumo dei crediti: i crediti vengono detratti al momento dell'invio. Il campo Charge nella risposta indica quanti crediti sono stati consumati.

La risposta restituisce { "Error": "Insufficient Credit", "Code": 202 } se l'account ha crediti insufficienti.

Scope OAuth : sms:send

Parametri

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

Risposte

Esempio 200

{
  "Id": 5001,
  "Message": "Your verification code is 8472. Valid for 10 minutes.",
  "ScheduledTime": "2026-04-15T14:30:00",
  "To": "0041791234567",
  "Charge": "1"
}

Esempio 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Esempio 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/list.{format}

Elenca le campagne SMS

Restituisce l'elenco delle campagne SMS (invii bulk) dell'account. Paginazione tramite gli header NumberOfRecords e PageNumber.

Usa type_to per filtrare per tipo di invio:

• 0 (default) — invii bulk verso una lista
• 1 — invii individuali singoli

Scope OAuth : sms:send

Parametri

Risposte

Esempio 200

[
  {
    "Id": 5001,
    "Message": "Your verification code is 8472",
    "ScheduledTime": "2026-04-15T09:00:00",
    "To": "41791234567"
  }
]

POST /send/del.{format}

Annulla o elimina un invio SMS

Annulla un invio SMS in attesa pianificato, oppure elimina un invio completato dallo storico. Solo gli invii pianificati nel futuro possono essere annullati. Gli invii in corso non possono essere fermati.

Scope OAuth : sms:send

Parametri

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

Risposte

Esempio 200

{
  "Result": "OK"
}

Esempio 500

{
  "Error": "Delete failed",
  "Code": 500
}

GET /send/scheduled.{format}

Elenca i miei invii SMS pianificati

Restituisce gli invii SMS (singoli o campagne) pianificati per una data futura che non sono ancora stati spediti. Utile prima di chiamare /cancel o /reschedule.

I record sono ordinati per scheduled_time crescente.

Scope OAuth : sms:send

Parametri

Risposte

Esempio 200

[
  {
    "Id": 9001,
    "Message": "Black Friday: 30% off until midnight.",
    "ScheduledTime": "2026-11-27T12:00:00",
    "To": "+33671234567"
  }
]

POST /send/{id_send}/cancel.{format}

Annulla un invio SMS pianificato

Annulla un SMS pianificato che non è ancora stato spedito. Se l'invio è già stato processato (o non esiste / appartiene a un altro client), restituisce 409 Conflict.

Scope OAuth : sms:send

Parametri

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

Risposte

Esempio 200

{
  "Result": "OK",
  "Cancelled": 9001
}

Esempio 409

{
  "error": "conflict",
  "message": "Send not found, not owned by client, or already dispatched."
}

PATCH /send/{id_send}/reschedule.{format}

Riprogramma un invio SMS pianificato

Aggiorna la data pianificata di un SMS programmato che non è ancora stato spedito. La nuova data deve essere nel futuro e entro 90 giorni.

Nome del campo data: l'API accetta scheduled_time (primario) così come gli alias legacy PlanDate, date_planned e DatePlanned. Fornisci uno qualsiasi di essi — viene usato il primo non null.

Scope OAuth : sms:send

Parametri

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

Risposte

Esempio 200

{
  "Result": "OK",
  "Id": 9001,
  "NewScheduledTime": "2026-12-31T14:30:00"
}

Esempio 409

{
  "error": "conflict",
  "message": "Reschedule failed — send not found, already dispatched, or new date out of range."
}

GET /list/list.{format}

Elenca le liste di contatti telefonici

Restituisce tutte le liste di contatti SMS dell'account. Usa i valori Id restituiti per inviare campagne SMS bulk o aggiungere numeri di telefono.

Scope OAuth : sms:contacts:read

Parametri

Risposte

Esempio 200

{
  "Items": [
    {
      "AddressBookId": 42,
      "Name": "Newsletter subscribers",
      "TotalNumberPhones": 1547
    },
    {
      "AddressBookId": 43,
      "Name": "Loyalty program",
      "TotalNumberPhones": 823
    }
  ]
}

POST /list/add.{format}

Crea una lista di contatti

Crea una nuova lista di contatti SMS con il nome indicato. La lista parte vuota — aggiungi i numeri di telefono con POST /phone/add. Massimo 1.000 liste per account (stesso limite sulle tre API Mailpro e nell'app). Restituisce HTTP 422 se il limite è raggiunto.

Parametri

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

Risposte

Esempio 200

{
  "Id": 44,
  "Name": "Spring campaign 2026",
  "NumberPhones": 0
}

Esempio 400

{
  "Error": "Malformed Input",
  "Code": 103
}

POST /list/edit.{format}

Rinomina una lista di contatti

Aggiorna il nome visualizzato di una lista di contatti SMS esistente. I numeri di telefono presenti nella lista non vengono modificati.

Scope OAuth : sms:contacts:write

Parametri

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

Risposte

POST /list/del.{format}

Elimina una lista di contatti

Elimina definitivamente una lista di contatti SMS e tutti i numeri di telefono che contiene. Questa azione non può essere annullata.

Scope OAuth : sms:contacts:write

Parametri

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

Risposte

GET /phone/list.{format}

Elenca i numeri di telefono in una lista di contatti

Restituisce un elenco paginato dei numeri di telefono in una specifica lista di contatti. Usa address_book_id per specificare quale lista recuperare. Paginazione: NumberOfRecords e PageNumber (5.000 per pagina per impostazione predefinita, pagina 1).

Scope OAuth : sms:contacts:read

Parametri

Risposte

Esempio 200

{
  "Items": [
    {
      "Id": 1001,
      "Number": "41791234567",
      "FirstName": "Alice",
      "LastName": "Dupont"
    },
    {
      "Id": 1002,
      "Number": "33612345678",
      "FirstName": "Bob",
      "LastName": "Martin"
    }
  ]
}

POST /phone/add.{format}

Aggiungi numero/i di telefono a una lista

Aggiunge uno o più numeri di telefono a una lista di contatti.

Numero singolo: usa il campo number.

Import bulk: usa il campo phone_list con i numeri separati da punto e virgola: +41791234567;+33612345678;0049301234567

I numeri di telefono accettano il formato +, 00 o quello puro — consulta Formato del numero di telefono nella descrizione dell'API per l'elenco completo degli input accettati / rifiutati. I numeri duplicati vengono saltati silenziosamente a meno che non sia impostato force=1.

Scope OAuth : sms:contacts:write

Parametri

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

Risposte

Esempio 200

{
  "Id": 1003,
  "Number": "0041791234567",
  "FirstName": "Alice",
  "LastName": "Dupont"
}

POST /phone/edit.{format}

Aggiorna una voce di numero di telefono

Aggiorna il numero di telefono e/o i dettagli del contatto di una voce esistente. Usa number_id (da /phone/list) per identificare la voce da aggiornare. Vengono aggiornati solo i campi forniti nella richiesta.

Scope OAuth : sms:contacts:write

Parametri

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

Risposte

POST /phone/del.{format}

Rimuovi un numero di telefono da una lista

Rimuove definitivamente una specifica voce di numero di telefono dalla sua lista di contatti. Usa number_id (da /phone/list) per identificare la voce.

Scope OAuth : sms:contacts:write

Parametri

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

Risposte

GET /credit/get.{format}

Ottieni il saldo dei crediti SMS

Restituisce il saldo corrente dei crediti SMS per il tuo account. I crediti SMS vengono consumati al momento dell'invio. Un SMS standard (≤160 caratteri GSM-7) costa 1 credito. I messaggi più lunghi o con caratteri speciali possono costare di più.

> Nota: questo restituisce il tuo saldo crediti di invio SMS, non la tua quota di richieste API. > Per la quota API vedi GET /account/limits.{format}.

Scope OAuth : sms:read

Parametri

Risposte

Esempio 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

Elenca lo storico degli invii SMS

Restituisce un log paginato di tutte le campagne SMS passate inviate da questo account. I risultati sono ordinati per data decrescente (più recenti per primi). Paginazione: NumberOfRecords e PageNumber (header o query, 5.000 per pagina per impostazione predefinita).

Scope OAuth : sms:read

Parametri

Risposte

Esempio 200

{
  "Items": [
    {
      "Id": 583294,
      "DateSent": "2026-07-17T18:56:39.813",
      "Message": "Your verification code is 8472",
      "Charge": 3,
      "Parts": 1
    }
  ]
}

POST /import/upload.{format}

Carica un file di numeri di telefono (CSV / XLSX) per l'import bulk

Carica un file CSV o XLSX per importare numeri di telefono in una lista di contatti. Il file viene memorizzato e accodato per l'elaborazione asincrona — l'endpoint restituisce immediatamente un ImportJobId.

Tipo di richiesta: multipart/form-data

Campi del form obbligatori:

• id_client (intero) — il tuo ID client Mailpro
• api_key (stringa) — la tua API key
• id_list (intero) — ID della lista di contatti di destinazione
• file (binario) — il file CSV o XLSX da caricare

Opzionale:

• 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
• Prima riga = intestazioni (una deve essere Phone o PhoneNumber — case-insensitive)
• Numeri in formato internazionale (E.164), es. +41791234567
• Dimensione massima del file: 50 MB

Scope OAuth : sms:contacts:write

Parametri

Corpo della richiesta (multipart/form-data)

Risposte

Esempio 200

{
  "Result": "OK",
  "ImportJobId": 15,
  "InternalName": "230575-20260420142616-phones.csv"
}

GET /webhooks

Elenca i webhook

Restituisce ogni webhook configurato sull'account autenticato.

Risposte

Esempio 200

{
  "items": [
    {
      "id": 14,
      "url": "https://example.com/hooks/mailpro",
      "description": "Integrazione Slack",
      "is_active": true,
      "created_at": "2026-07-01T21:09:52.43",
      "updated_at": "2026-07-21T18:56:08.02",
      "last_delivery_at": "2026-07-21T18:56:07.653",
      "last_delivery_status": 200,
      "consecutive_failures": 0,
      "events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "total": 1
}

POST /webhooks

Crea un webhook

Crea una nuova sottoscrizione webhook. La risposta contiene un secret che viene mostrato una sola volta — conservalo immediatamente, lato server. Usalo 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": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Integrazione Slack"
}

Risposte

Esempio 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "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 /webhooks/{id}

Ottieni un webhook

Parametri

Risposte

PUT /webhooks/{id}

Aggiorna un webhook

Aggiornamento parziale — vengono modificati solo i campi inviati.

Parametri

Corpo della richiesta (application/json)

Risposte

DELETE /webhooks/{id}

Elimina un webhook

Elimina definitivamente il webhook e tutto il suo storico di consegne.

Parametri

Risposte

POST /webhooks/{id}/test

Invia un evento di test

Accoda un evento ping immediato (o qualsiasi altro tipo di evento tramite il campo eventType nel body) verso il tuo endpoint. Utile per verificare la raggiungibilità e la verifica della firma prima di basarsi su eventi reali.

Parametri

Corpo della richiesta (application/json)

Esempio

{
  "eventType": "ping"
}

Risposte

Esempio 202

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

POST /webhooks/{id}/rotate-secret

Ruota il segreto HMAC

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

Usalo se sospetti che il tuo segreto sia stato compromesso.

Parametri

Risposte

Esempio 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{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, conteggi dei retry, messaggi di errore.

Parametri

Risposte

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

Riproduci una consegna

Accoda un nuovo tentativo di consegna con lo stesso payload dell'originale. Utile per ri-scatenare una consegna fallita dopo aver corretto il tuo endpoint. Viene creata una NUOVA riga Webhook_Delivery (l'originale viene preservata per audit). La riproduzione segue la policy di retry standard (stesso schedule di backoff, stessa regola di auto-disabilitazione a 10 fallimenti).

Parametri

Risposte