Invio Email (beta)


L'invio email è una funzionalità del Piano Premium. Se utilizzi il piano Starter attiva gratis il tuo periodo di prova del Piano Premium.
Per poter utilizzare le API elencate in questa pagina è necessario richiedere la specifica abilitazione.
RICHIEDI ABILITAZIONE

Lista Mittenti

Restituisce la lista dei mittenti configurati dall'utente tramite interfaccia web.

URI

GET https://api.smshosting.it/rest/api/email/sender/list


Richiesta

ParametroObbligatorioTipoDescrizione
Nessun parametro

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/sender/list
[
    {
        "id": 1,
        "email": "mrbrown@fake.com",
        "emailName": "Mr. Brown",
        "validationDate": "2020-03-13T14:40:51+0100",
        "insertDate": "2020-03-13T14:33:30+0100",
        "contactCompany": "G",
        "contactAddress": "via Roma",
        "contactCity": "Belluno",
        "contactProvince": "BL",
        "contactZipCode": "32100,
        "contactCountry": "IT",
        "contactPhone": ""
    }
]

Lista Modelli

Restituisce la lista dei modelli creati dall'utente tramite interfaccia web.

URI

GET https://api.smshosting.it/rest/api/email/template/list


Richiesta

ParametroObbligatorioTipoDescrizione
offset No Integer

Posizione del primo risultato che verrà restituito.

Esempio:

Se il campo offset viene valorizzato a 50 e il campo limit a 10 verranno restituiti i template da 51 a 60.

Default: 0

limit No Integer

Numero massimo di risultati che verranno restituiti nella ricerca.

Default : 20

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/template/list
{
    "metadata": {
        "count": 2,
        "offset": 0,
        "limit": 20
    },
    "templates": [
        {
            "id": 2038,
            "title": "Modello Uno",
            "editorType": "B",
            "contentType": "multipart/alternative",
            "insertDate": "2020-06-30T13:48:27+0200",
            "updateDate": "2020-06-30T14:33:33+0200",
            "customFieldsKey": [
                "f_s_nome"
            ]
        },
        {
            "id": 299,
            "title": "test",
            "editorType": "B",
            "contentType": "multipart/alternative",
            "insertDate": "2020-04-10T12:27:37+0200",
            "updateDate": "2020-04-10T12:27:50+0200"
        }
    ]
}

Dettaglio Modello

Restituisce il dettaglio di un singolo modello email. Il dettaglio contiene anche il campo customFieldsKey che contiene l'id dei campi dinamici da compilare all'interno del template

URI

GET https://api.smshosting.it/rest/api/email/template/{templateId}


Richiesta

ParametroObbligatorioTipoDescrizione
Nessun parametro

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/template/2038
{
    "id": 2038,
    "title": "Modello Orange Friday",
    "editorType": "B",
    "contentType": "multipart/alternative",
    "insertDate": "2020-06-30T13:48:27+0200",
    "updateDate": "2020-07-01T10:38:46+0200",
    "customFieldsKey": [
        "f_s_nome"
    ]
}

Lista Campagne Email

Restituisce la lista delle campagne email inviate

URI

GET https://api.smshosting.it/rest/api/email/campaign/list


Richiesta

ParametroObbligatorioTipoDescrizione
offset No Integer

Posizione del primo risultato che verrà restituito.

Esempio:

Se il campo offset viene valorizzato a 50 e il campo limit a 10 verranno restituiti i template da 51 a 60.

Default: 0

limit No Integer

Numero massimo di risultati che verranno restituiti nella ricerca.

Default : 20

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/campaign/list
{
    "metadata": {
        "count": 2,
        "offset": 0,
        "limit": 5
    },
    "campaignList": [
        {
            "id": 2385,
            "campaignTitle": "Invio Orange Friday",
            "templateId": 2038,
            "from": "mr.brown@fake.it",
            "fromName": "Orange Friday",
            "subject": "Why only black? Get the orange",
            "subjectPreviewText": "Orange Friday 2020",
            "enableOpenTracking": true,
            "enableLinkTracking": true,
            "stats": {
                "countEmailInserted": 1,
                "countEmailStatusPending": 0,
                "countEmailStatusNoSent": 0,
                "countEmailTotSent": 1,
                "countEmailStatusBounced": 0,
                "countEmailOpenedUnique": 1,
                "countEmailClickUnique": 0,
                "countEmailStatusSpamReport": 0,
                "countEmailCauseUnsubscribed": 0
            }
        },
        {
            "id": 2570,
            "campaignTitle": "Invio Blue Monday",
            "templateId": 2385,
            "from": "mr.brown@fake.it",
            "fromName": "Mr. Brown",
            "subject": "Why only black? Get the blue",
            "subjectPreviewText": "Get the blue today!",
            "enableOpenTracking": false,
            "enableLinkTracking": false,
            "stats": {
                "countEmailInserted": 9,
                "countEmailStatusPending": 0,
                "countEmailStatusNoSent": 0,
                "countEmailTotSent": 9,
                "countEmailStatusBounced": 0,
                "countEmailOpenedUnique": 0,
                "countEmailClickUnique": 0,
                "countEmailStatusSpamReport": 0,
                "countEmailCauseUnsubscribed": 0
            }
        }
    ]
}

Dettaglio Campagna Email

Restituisce il dettaglio con i dati e le statistiche di una singola campagna email.

URI

GET https://api.smshosting.it/rest/api/email/{emailId}


Richiesta

ParametroObbligatorioTipoDescrizione
Nessun parametro

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

CAMPAIGN_NOT_EXISTS - La campagna email non esiste

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/338
{
    "id": 338,
    "campaignId": 4,
    "templateId": 38,
    "to": "msbrown@fake.com",
    "status": "DELIVERED",
    "statusDate": "2020-03-17T11:02:39+0100",
    "insertDate": "2020-03-17T11:00:03+0100",
    "sentDate": "2020-03-17T11:02:35+0100"
}

Dettaglio Email

Restituisce il dettaglio di una singola email inviata.

URI

GET https://api.smshosting.it/rest/api/email/{emailId}


Richiesta

ParametroObbligatorioTipoDescrizione
Nessun parametro

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
   -XGET https://api.smshosting.it/rest/api/email/338
{
    "id": 338,
    "campaignId": 4,
    "templateId": 38,
    "to": "msbrown@fake.com",
    "status": "DELIVERED",
    "statusDate": "2020-03-17T11:02:39+0100",
    "insertDate": "2020-03-17T11:00:03+0100",
    "sentDate": "2020-03-17T11:02:35+0100"
}

Invio Campagna

Permette di inviare una campagna email ad un gruppo di contatti della rubrica.

URI

POST https://api.smshosting.it/rest/api/email/campaign/send


Richiesta

  Il "Content-Type" per le richieste POST deve essere "multipart/form-data"
ParametroObbligatorioTipoDescrizione
templateId Si Integer

Id del template da utilizzare per l'invio, può essere recuperato da interfaccia web dalla pagina di dettaglio del modello. Per vedere il dettaglio clicca: Email -> Modelli -> Modifica Modello -> "Identificativo interno"

from Si String

Indirizzo email del mittente dell'invio, deve essere un mittente verificato da interfaccia web

fromName No String

Nome che comparirà al destinatario come mittente dell'email

group Si Integer

Id del gruppo a cui inviare l'email, recuperabile da interfaccia web o tramite la chiamata Gruppi Rubrica -> Lista Gruppi

subject Si String

Oggetto dell'email

subjectPreviewText No String

Anteprima del testo dell'email visualizzata in alcuni client

campaignTitle Si String

Titolo della campagna email

enableOpenTracking No Boolean

Se impostato a false disabilita il tracciamento per l'apertura dell'email

Default: true

enableLinkTracking No Boolean

Se impostato a false disabilita il tracciamento per i click sui link presenti nell'email

Default: true

date No String

Invia la campagna alla data e ora specificate nel formato yyyy-MM-dd'T'HH:mm:ssZ

sandbox No Boolean

Se impostato a true simula l'invio senza inviare realmente le email

Default: false

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

BAD_TEMPLATEID - Identificativo del template mancante o template non esistente

BAD_FROM - Indirizzo email del mittente mancante o mittente non verificato

BAD_GROUP - Identificativo del gruppo mancante o non esistente

BAD_SUBJECT - Oggetto dell'email mancante

BAD_CAMPAIGN_TITLE - Titolo della campagna mancante

BAD_DATE - Data in formato errato o non coerente

NO_CREDIT - Il numero di mail residue non è sufficiente ad inviare la campagna

GENERIC_ERROR - Errore generico

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
    -XPOST https://api.smshosting.it/rest/api/email/campaign/send \
    -d 'templateId=2038' \
    -d 'from=mrbrown@fake.it' \
    -d 'fromName=Orange Friday' \
    -d 'group=103838' \
    -d 'subject=Why only black? Get the orange' \
    -d 'subjectPreviewText=Orange Friday 2020' \
    -d 'campaignTitle=Invio Orange Friday' \
    -d 'sandbox=true'
{
    "campaignId": 2538,
    "emailInserted": 38,
    "emailNotInserted": 0
}

Invio Email Singola

Permette di inviare una singola email ad un massimo di 50 destinatari anche non inseriti in un gruppo della rubrica.

URI

POST https://api.smshosting.it/rest/api/email/{emailId}


Richiesta

  Il "Content-Type" per le richieste POST deve essere "multipart/form-data"
ParametroObbligatorioTipoDescrizione
templateId Si Integer

Id del template da utilizzare per l'invio, può essere recuperato da interfaccia web dalla pagina di dettaglio del modello. Per vedere il dettaglio clicca: Email -> Modelli -> Modifica Modello -> "Identificativo interno"

from Si String

Indirizzo email del mittente dell'invio, deve essere un mittente verificato da interfaccia web

fromName No String

Nome che comparirà al destinatario come mittente dell'email

to Si String

Destinatario della mail in uno dei seguenti formati:

  • destinatario singolo ms.green@fake.it
  • una lista fino a 50 destinatari in formato json che può contenere anche i campi personalizzati da sostituire nel testo: [{'to':'ms.green@fake.it','f_s_nome':'Ms Green'},{'to':'mr.yellow@fake.it','f_s_nome':'John Yellow'}]
subject Si String

Oggetto dell'email

subjectPreviewText No String

Anteprima del testo dell'email visualizzata in alcuni client

enableOpenTracking No Boolean

Se impostato a false disabilita il tracciamento per l'apertura dell'email

Default: true

enableLinkTracking No Boolean

Se impostato a false disabilita il tracciamento per i click sui link presenti nell'email

Default: true

date No String

Invia l'email alla data e ora specificate nel formato yyyy-MM-dd'T'HH:mm:ssZ

sandbox No Boolean

Se impostato a true simula l'invio senza inviare realmente le email

Default: false

Risposta

HTTP Status Code

CodiceDescrizione
200 ok
400

I possibili errorMsg sono:

BAD_TEMPLATEID - Identificativo del template mancante o template non esistente

BAD_FROM - Indirizzo email del mittente mancante o mittente non verificato

BAD_GROUP - Identificativo del gruppo mancante o non esistente

BAD_SUBJECT - Oggetto dell'email mancante

BAD_TO_SIZE - Troppi destinatari

BAD_DATE - Data in formato errato o non coerente

NO_CREDIT - Il numero di mail residue non è sufficiente ad inviare la campagna

GENERIC_ERROR - Errore generico

PLAN_NOT_ENABLED - Questa chiamata non è permessa nel piano utente

401 Credenziali non valide
405 Metodo HTTP non consentito
500 Errore generico

 Esempio:

   curl --user AUTH_KEY:AUTH_SECRET \
    -XPOST https://api.smshosting.it/rest/api/email/campaign/send \
    -d 'templateId=2038' \
    -d 'from=mrbrown@fake.it' \
    -d 'fromName=Orange Friday' \
    -d 'to=[{'\''to'\'':'\''ms.green@fake.it'\'','\''f_s_nome'\'':'\''Clara'\''},{'\''to'\'':'\''mr.yellow@fake.it'\'','\''f_s_nome'\'':'\''John'\''}]' \
    -d 'subject=Why only black? Get the orange' \
    -d 'subjectPreviewText=Orange Friday 2020' \
    -d 'sandbox=true'
{
    "emailInserted": 2,
    "emailNotInserted": 0,
    "email": [
        {
            "id": 869382,
            "to": "ms.green@fake.it",
            "status": "INSERTED"
        },
        {
            "id": 869383,
            "to": "mr.yellow@fake.it",
            "status": "INSERTED"
        }
    ]
}