Helpdesk
English Flag

API Email Hosting - Web Prato

Webprato mette a disposizione dei propri clienti ed utenti la possibilità di gestire i servizi di Email Hosting mediante API. Tutte le principali funzioni disponibili nel nostro pannello di controllo hanno una corrispondente chiamata API per la loro implementazione. E’ quindi possibile per i clienti implementare funzionalità e sistemi di automazione direttamente nei loro attuali sistemi di gestione/fatturazione.

La disponiblità delle API di Webprato offre la possibilità di creare una propria piattaforma per l’Email Hosting, in modalità PaaS, senza dover utilizzare i nostri pannelli di controllo.

NOTA: la documentazione delle API è in fase di completamento, ci vorrà ancora qualche settimana di lavoro Introduzione

Introduzione

Le API di Webprato viaggiano sul protocollo HTTP e sono di tipo RESTful, inoltre:

Fanno riferimento ad un URL per tutte le chiamate
Usano lo standard HTTP per l’invio dei dati di autenticazione ed i parametri
Rispondono con codici appartenenti allo standard HTTP
Ritornano informazioni in formato JSON
Gli esempi che qui riporteremo usano curl ma le stesse funzioni possono essere implementate in un qualsiasi linguaggio di programmazione orientato al web.

Per testare le API è consigliabile l’uso di un client REST come plugin per il proprio browser. Per chi utilizza Firefox, Chrome, Safari è possibile utilizzare questo ottimo plugin: http://restclient.net/
Base URL

Tutte le chiamate alle API di Webprato devono avere il seguente URL come base:
https://apimail.cbsolt.net/api/v1/

A seconda del dominio o dell’account email con il quale stiamo lavorando il base url varierà come segue:

https://apimail.cbsolt.net/api/v1/domains/D12345678/email_accounts

in questo modo non è necessario passare il codice del dominio come parametro.

Autenticazione
Prima di poter iniziare ad utilizzare le API è necessario essere in possesso del token per l’autenticazione. Si tratta di un codice ASCII univoco generato per il proprio utente dal pannello di controllo. Ogni utente può generare o cancellare l’API Token nella sezione “Il mio Account” dal pannello di controllo di Webprato.

Im12

Il token va passato alle API come valore dell’header HTTP dal nome “X-API-TOKEN”:

X-API-TOKEN: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Grazie al token non è necessario utilizzare nelle API il nome utente e la password. Per bloccare l’uso delle API è sufficiente rimuovere il proprio token.

ATTENZIONE: conservare il proprio API Token con estrema sicurezza, anche la sua generazione ed utilizzo deve avvenire solo in presenza di connessioni sicure SSL (HTTPS). Il suo furto potrebbe portare gravi danni o perdita di dati al vostro account.

Metodi HTTP
A seconda del tipo di operazione che si deve andare a compiere si deve utilizzare un metodo HTTP differente:

  • GET: Per il recupero di informazioni sulle risorse
  • POST: Per la creazione di nuove risorse
  • PUT: Per la modifica di risorse esistenti
  • DELETE: Per la cancellazione di una risorsa

Alcuni client (come i browser) non supportano altri metodi oltre a GET e POST, per questi è possibile fare un ovverride del metodo desiderato utilizzando POST e il parametro aggiuntivo _method (con valore PUT o DELETE ad esempio).

Codici di risposta HTTP
Le API restituiscono dei codici standard HTTP in modo da dare informazione all’utente se una richiesta è andata a buon fine o meno. I codici ad oggi utilizzati sono:

  • 200: Richiesta accettata con successo
  • 202: Richiesta accettata con successo e risposta inviata
  • 201: Richiesta accettata e risorsa messa in coda per la creazione
  • 206: Richiesta accettata e risorsa messa in coda per la modifica
  • 401: Richiesta non autorizzata/Login invalido
  • 403: Richiesta non autorizzata/Login invalido/Sessione scaduta
  • 404: Risorsa non trovata
  • 500: Richiesta invalida/Possibile errore in Webprato

Tipi di utente e ruoli
Alle API di Webprato possono accedere tutti i tipi di utenti disponibili, ovviamente ognuno di essere avrà accesso alle sole informazioni a lui riservate. I tipi di utenti sono:

  • Customer: il cliente Webprato
  • Manager: gestito dai customer
  • Postmaster: gestisce solo il suo dominio
  • User: l’utilizzato dell’account email

Lista delle chiamate e loro parametri
Informazioni Account

  • Utente: tutti
  • Metodo: GET
  • URL: https://apimail.cbsolt.net/api/v1/account
  • Parametri: nessuno

Esempio:
curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://apimail.cbsolt.net/api/v1/account

Risposta del server:

{
“resource”: {
“code”: “7446428345”,
“domain_code”: “D12345678”,
“role”: “postmaster”,
“email”: “postmaster@cbsolt.it”,
“firstname”: “postmaster”,
“lastname”: “cbsolt.it”,
“fullname”: “postmaster@cbsolt.it”,
“fullname_with_code”: “postmaster@cbsolt.it [7446428345]”,
“max_email_quota”: “52428800”,
“email_pop_disabled”: false,
“email_webmail_disabled”: false,
“email_imap_disabled”: false,
“email_smtp_disabled”: false
},
“status”: 200,
“message”: “Returned content”
}

Lista Domini

  • Utente: Customer, Manager, Postmaster
  • Metodo: GET
  • URL: https://apimail.cbsolt.net/api/v1/domains
  • Parametri: nessuno

Esempio: curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://apimail.cbsolt.net/api/v1/domains
Risposta del server:

{
“counters”: {
“all”: 1,
“enabled”: 1,
“blocked”: 0,
“queued”: 0,
“unhealthy”: 0,
“not_assigned”: 1
},
“resources”: [
{
“code”: “D12345678”,
“name”: “cbsolt.it”,
“state”: “enabled”,
“state_detail”: “”,
“health_state”: “healthy”,
“customer_code”: null,
“manager_codes”: “”,
“customer_fullname”: null,
“customer_fullname_with_code”: null,
“possession_a_record”: “”,
“max_email_accounts”: -1,
“max_email_quota”: “1073741824”,
“email_pop_disabled”: false,
“email_webmail_disabled”: false,
“email_imap_disabled”: false,
“email_smtp_disabled”: false,
“max_mailing_lists”: 2,
“catch_all_enabled”: false,
“catch_all_activated”: false,
“catch_all_destination”: null,
“alias_domains_count”: 2,
“email_accounts_count”: 18,
“alias_emails_count”: 6,
“postmaster”: {
“code”: “7446428345”,
“state”: “enabled”,
“state_detail”: “”,
“email_pop_disabled”: false,
“email_webmail_disabled”: false,
“email_imap_disabled”: false,
“email_smtp_disabled”: false,
“description”: “Postmaster”,
“bounce_mail”: false,
“keep_copy”: true,
“forwards”: “mario.rossi@cbsolt.it”,
“autoresponder_enabled”: false,
“autoresponder_subject”: “”,
“autoresponder_content”: “”,
“max_email_quota”: “52428800”,
“current_quota”: 13878534,
“current_lastauth”: “pop3:1382620704”
}
}
],
“paginator”: {
“currents”: 1,
“totals”: 1,
“current_page”: 1,
“limit”: 25,
“total_pages”: 1
},
“filters”: {
“selection”: “all”,
“customer_code”: null,
“query”: null,
“query_type”: “alls”,
“sort_field”: “name”,
“sort_dir”: “asc”,
“page”: 1,
“per”: 25
}
“status”: 200,
“message”: “Returned content”
}

Lista Account Mail per Dominio

  • Utente: Customer, Manager, Postmaster
  • Metodo: GET
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/email_accounts
  • Parametro: codice dominio (es. D12345678) direttamente nell’URL

Esempio: curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://apimail.cbsolt.net/api/v1/domains/D12345678/email_accounts

Lista Email Alias per Dominio

  • Utente: Customer, Manager, Postmaster
  • Metodo: GET
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails
  • Parametro: codice dominio (es. D12345678) direttamente nell’URL

Esempio: curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails

Lista Domini Alias per Dominio

  • Utente: Customer, Manager, Postmaster
  • Metodo: GET
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_domains
  • Parametro: codice dominio (es. D12345678) direttamente nell’URL

Esempio: curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_domains

Dettagli Account Email

  • Utente: Customer, Manager, Postmaster, Utente
  • Metodo: GET
  • URL: https://gestionemail.cbsolt.net/api/v1/domains/D12345678/email_accounts/12345678
  • Parametro: codice dominio (es. D12345678) e id account email (es. 12345678) direttamente nell’URL

Esempio: curl -H “X-API-TOKEN: XXXXXXXXXXXXXX” -X GET https://gestionemail.cbsolt.net/api/v1/domains/D12345678/email_accounts/12345678

Risposta del server:

{
“resource”: {
“code”: “12345678”,
“name”: “mario.rossi”,
“fullemail”: “mario.rossi@cbsolt.it”,
“state”: “enabled”,
“state_detail”: “”,
“max_email_quota”: “1073741824”,
“current_quota”: 12454289,
“current_lastauth”: “imap:1383054645”,
“email_pop_disabled”: false,
“email_webmail_disabled”: false,
“email_imap_disabled”: false,
“email_smtp_disabled”: false,
“description”: “Mario Rossi”,
“bounce_mail”: false,
“keep_copy”: true,
“forwards”: “mario.rossi@gmail.com”,
“autoresponder_enabled”: false,
“autoresponder_subject”: “”,
“autoresponder_content”: “”
},
“status”: 200,
“message”: “Returned content”
}

Cambio Password Account Email

  • Utente: Customer, Manager, Postmaster, Utente
  • Metodo: PUT
  • URL: https://gestionemail.cbsolt.net/api/v1/domains/D12345678/email_accounts/12345678
  • Parametri: password attuale=current_email_password (solo per Utente) nuova password=email_password conferma nuova password=email_password_confirmation

Esempio: curl -F email_password=’xxxxyyy123′ -F email_password_confirmation=’xxxxyyy123′ -H “X-API-TOKEN: XXXXXXXXXXXXX” -X PUT https://gestionemail.cbsolt.net/api/v1/domains/D12345678/email_accounts/12345678

Risposta del server:

{
“status”: 206,
“message”: “No content needed”
}

Creazione Alias Email

  • Utente: Customer, Manager, Postmaster
  • Metodo: POST
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails
  • Parametri: nome alias=name destinazione=destination id dominio=domain_id

Esempio: curl -F name=’info’ -F destination=’mario.rossi@cbsolt.it’ -F domain_id=’D12345678′ -X POST -H “X-API-TOKEN: XXXXXXXXXXXXXX” https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails

Modifica Alias Email

  • Utente: Customer, Manager, Postmaster
  • Metodo: PUT
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails/AE12345678
  • Parametri: destinazione=destination (se multipli separati da virgola) id dominio=domain_id id alias=id

Esempio: curl -F destination=’postmaster@cbsolt.it,mario.rossi@cbsolt.it,info@cbsolt.it‘ -F domain_id=’D12345678′ -F id=’AE12345678’ -X POST -H “X-API-TOKEN: XXXXXXXXXXXXXX” https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails

Cancellazione Alias Email

  • Utente: Customer, Manager, Postmaster
  • Metodo: DELETE
  • URL: https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails/AE12345678
  • Parametri: id dominio=domain_id id alias=id

Esempio: curl -F domain_id=’D12345678′ -F id=’AE12345678′ -X DELETE -H “X-API-TOKEN: XXXXXXXXXXXXXX” https://apimail.cbsolt.net/api/v1/domains/D12345678/alias_emails

Web Prato srl (c) 2002-2017 - Tutti i diritti riservati -- Sede Legale: Via Baracca 78, 59100 Prato (PO)
Sede Operativa Via Zarini 266, 59100 Prato - Codice fiscale/Partita IVA 01891850974 - Capitale Sociale € 10.000,00