Primi passi

Un introduzione per capire come funzionano le API del servizio di Managed Mail Server in Cloud di Qboxmail.

Codici di risposta

Questa è la lista dei codici di ritorno che possono restituire le chiamate alle API di Qboxmail. Di fianco ad ogni codice è riportato il suo significato:

  • 200: successful request
  • 201: successful request, resource enqueued for creation
  • 202: successful request, response sent
  • 206: successful request, resource enqueued for modification
  • 401: unauthorized request, invalid login
  • 403: unauthorized request session expired
  • 404: resource not found
  • 500: invalid request/server error

Di norma il codice di ritorno è 200 se la funziona chiamata è sincrona, altre chiamate come la creazione di un dominio passano da una coda di elaborazione quindi ritornano un codice 201.

Struttura completa di una risposta

Ecco un esempio di come si presenta la risposta completa di una chiamata alle API di Qboxmail. Il formato del dato è di tipo JSON:

{
   "counters":{
      "all":4,
      "enabled":3,
      "blocked":1,
      "queued":0,
      "unhealthy":1,
      "not_assigned":0
   },
   "resources":[
      ...
   ],
   "paginator":{
      "currents":4,
      "totals":4,
      "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"
}

Ciascuna risposta può avere fino a 4 differenti contesti:

  • counters : rappresenta il contatore per tutti i tipo di una risorsa, da qui puoi vedere il totale delle risorse ed il totale diviso per categorie (es. domini: totali, attivi, in attesa di verifica della proprietà, con problemi DNS)
  • resources : questo è l’array con la lista ed il dettaglio di tutte le risorse restituite dalla chiamata alle API (es. la lista dei domini ed il numero di caselle email attive per ognuno)
  • paginator : qui è restituito il numero totale delle risorse recuperato e le informazioni sulla loro paginazione
  • filters : da qui si possono vedere alcune informazioni sui filtri disponibili per il set di dati restituito

Convenzioni utilizzate

Ecco le convenzioni di forma che devi sapere quando leggi la documentazione delle API di Qboxmail:

  • #{text}: Indica un campo che deve essere rimpiazzato con un tuo specifico parametro
  • … : Significa che il contenuto della risposta (del server) è stato tagliato per motivi di spazio

Qualcosa non ti è chiaro?

Se leggendo la documentazione noti delle mancanze, degli errori o c’è qualcosa che non ti è chiaro scrivici a support@qboxmail.it e saremo felici di risponderti.

Autenticazione via Token

Prima di iniziare ad utilizzare le API di Qboxmail è necessario generare il token che ti servirà per autenticarti ad ogni chiamata. Puoi generarlo accedendo al pannello di controllo, sotto la voce “Il mio account“. Qui trovi un menù dove è possibile generare, visualizzare o cancellare il token in uso:

go to my account for creating a new token

Una volta generato il token deve essere passato a tutte le chiamate API come header HTTP in questa forma:

X-API-TOKEN: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Ecco un esempio di una chiamata alle API per recuperare le informazioni di uno specifico dominio:

curl -H “X-API-TOKEN:XXXXXXXXX” -X get https://apimail.cbsolt.net/api/v1/domains/D04081991

RICORDA: il token va conservato con estrema sicurezza e non deve essere rivelato a nessuno, inoltre verifica sempre di inviare le chiamate alle API utilizzando il protocollo sicuro HTTPS

Come interagire con le API

Le API di Qboxmail sono implementate nel formato JSON inviato attraverso il protocollo HTTP. I nostri “Endpoints” sono di tipo RESTFul ed è possibile chiamargli con i classici metodi HTTP: GET, PUT, POST e DELETE. Tutte le risorse, Domini, Email, Alias e la gestione utenti, hanno il loro URI in modo da essere gestite in maniera sicura ed isolate dalle restanti risorse.

Per testare velocemente le nostre API puoi installare un plugin che in grado di inviare e ricevere chiamate “restful” sul tuo browser Mozilla Firefox, Google Chrome o Safari:

Restclient

Base URL

Il “base url” è l’indirizzo a cui devono essere inviate tutte le richieste alle API:

https://apimail.cbsolt.net/api/v1/

Email Alias

Praesent venenatis metus at tortor pulvinar varius. Vestibulum ullamcorper mauris at ligula. Cras non dolor. Nunc nulla.

Struttura

  • code il codice che identifica un email alias in maniera univoca
  • destination: string that represent the email address that will receive the emails
  • name string
  • state the state of the domain, can be active, disabled or blocked.
  • state_detail the explanation of the current state

Create a alias Email Account

POST /domains/#{domain_code}/alias_emails

 

Argomenti
name Donec venenatis vulputate lorem

Cras dapibus. In ut quam vitae odio lacinia tincidunt. Aliquam lobortis. Morbi mollis tellus ac sapien. Morbi ac felis.

Praesent porttitor, nulla vitae posuere iaculis, arcu nisl dignissim dolor, a pretium mi sem ut ipsum. Aliquam lobortis. Cras risus ipsum, faucibus ut, ullamcorper id, varius ac, leo. Cras ultricies mi eu turpis hendrerit fringilla. Fusce fermentum odio nec arcu.

Duis leo. Donec id justo. Ut a nisl id ante tempus hendrerit. Quisque malesuada placerat nisl. Praesent ac sem eget est egestas volutpat.

destination
Esempio di richiesta
curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_emails -d "name=luigi@mario.it&destination=mario@mariolone.it"
Esempio di risposta
{
   "status":201,
   "message":"New resource created"
}

Domini e Caselle Email

Creazione, modifica e cancellazione di domini e relative caselle email (compresi domini alias, email alias e forward).

Email Alias

Structure

  • code il codice che identifica un email alias in maniera univoca
  • destination: string that represent the email address that will receive the emails
  • name string
  • state the state of the domain, can be active, disabled or blocked.
  • state_detail the explanation of the current state

For the full output see at the end of this page, the fields are name are fairly explicative

Create a alias Email Account

POST /domains/#{domain_code}/alias_emails

Mandatories Parameters
  • name
  • destination
response
{
   "status":201,
   "message":"New resource created"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_emails -d "name=luigi@mario.it&destination=mario@mariolone.it"

Edit an Alias Email Account

POST /domains/#{domain_code}/alias_emails/#{email_account_code}

Mandatory Parameters
  • destination
response
{
   "status":206,
   "message":"No content needed"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X put https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_emails/#{alias_email_account_code} -d "destination=mario@mario.it"

List Alias Email Accounts

GET /domains/#{domain_code}/alias_emails

response
{   ...,
   "resources":[
      {
         "code":"AE36546336",
         "name":"luigi",
         "fullemail":"luigi@mario.io",
         "state":"enabled",
         "state_detail":"",
         "destination":"mario@mario.com"
      }
   ],
   ...,
   "status":200,
   "message":"Returned content"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_emails

Delete Alias Email Account

DELETE /domains/#{domain_code}/alias_emails/#{alias_email_account_code}

You can retrieve the code of the alias email account you want to delete requesting the list of them before.

response
{
   "status":206,
   "message":"No content needed"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_emails/#{alias_email_account_code}

Caselle Email

Tutte le caselle email (dette anche Mailbox) in Qboxmail sono associate al loro dominio. Il nome utente per accedere alle caselle email (via POP/IMAP/SMTP/Webmail) coincide con l’indirizzo email.

Struttura

  • autoresponder_content string
  • autoresponder_enabled true | false
  • autoresponder_subject string
  • code il codice identificato della casella
  • description: string una descrizione della casella
  • email_imap_disabled true|false
  • email_pop_disabled true|false
  • email_smtp_disabled true|false
  • email_webmail_disabled true|false
  • forwards string la lista dei forward della casella email, massimo 10 separati da virgola
  • fullemail string l’indirizzo email completo
  • max_email_quota la quota massima della casella email espressa in bytes (1,2,3,4,5,6,7, 8 GB o, se l’opzione sul dominio è attiva, 16 e 25GB)
  • keep_copy true |false mantiene una copia locale delle email inoltrate ai forward
  • bounce_mail true |false disabilita la casella email inviando un messaggio di errore predefinito
  • state lo stato della casella email può essere active or blocked.
  • state_detail una spiegazione sullo stato corrente della casella email

Per un output completo della richiesta si veda in fondo alla pagina, i nomi dei campi sono autoesplicativi.

Creazione di una Casella Email

POST /domains/#{domain_code}/email_accounts

Parametri obbligatori
  • name
  • email_password
  • email_password_confirmation
  • max_email_quota
  • email_imap_disabled
  • email_pop_disabled
  • email_smtp_disabled
  • email_webmail_disabled
  • autoresponder_enabled
risposta
{
   "status":201,
   "message":"New resource created"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/email_accounts -d "name=luigi&email_password=Test12345&email_password_confirmation=Test12345&email_smtp_disabled=false&email_webmail_disabled=false&email_pop_disabled=false&email_imap_disabled=false&&autoresponder_enabled=false&max_email_quota=8589934592"

Modifica di una Casella Email

PUT /domains/#{domain_code}/email_accounts/#{email_account_code}

Parametri obbligatori
  • email_password
  • email_password_confirmation
risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X put https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/email_accounts/#{email_account_code} -d "email_password=Test12345&email_password_confirmation=Test12345&keep_copy=true"

Lista Caselle Email

GET /domains/#{domain_code}/email_accounts

risposta
{ ...,
   "resources":[
      {
         "code":"AD41364733",
         "name":"luigi",
         "domain_name":"mario.io",
         "state":"blocked",
         "state_detail":"ownership_check",
         "health_state":"healthy",
         "possession_a_record":"ad41364733"
      }
   ],
    ...,
   "status":200,
   "message":"Returned content"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/email_accounts

Cancellazione di una Casella Email

DELETE /domains/#{domain_code}/email_accounts/#{email_account_code}

Il codice del dominio alias da cancellare può essere recuperato dalla lista dei domini alias.

risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/email_accounts/#{email_account_code}

Dominio Alias

Un Dominio Alias in Qboxmail è sempre associato ad un (solo) dominio realeed ha le sue stessa caselle email ed alias. La differenza è che i messaggi inviati ad un dominio alias sono consegnati nelle caselle email del dominio reale.

Struttura

  • code: il codice che identifica il Customer proprietario del dominio
  • domain_name string il nome del dominio reale
  • name il nome del dominio alias
  • possession_a_record questo campo, valorizzato solo quando il dominio non è ancora attivo, indica il codice per la verifica della proprietà da inserire nel DNS del dominio. Trovi qui maggiori informazioni sulla verifica della proprietà del dominio
  • state the state of the domain, can be active, disabled or blocked.
  • state_detail una spiegazione sullo stato corrente del dominio

Per un output completo della richiesta si veda in fondo alla pagina, i nomi dei campi sono autoesplicativi.

Creazione di un dominio alias

POST domains/#{domain_code}/alias_domains

Parametri obbligatori
  • name
response
{
   "status":201,
   "message":"New resource created"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_domains -d "name=mario.it"

Lista dei Domini Alias

GET domains/#{domain_code}/alias_domains

risposta
{
   ...
   "resources":[
      {
         "code":"AD41364733",
         "name":"ripova.io",
         "domain_name":"provacremona.io",
         "state":"blocked",
         "state_detail":"ownership_check",
         "health_state":"healthy",
         "possession_a_record":"ad41364733"
      }
   ],
   ...,
   "status":200,
   "message":"Returned content"
}
Esempio curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_domains

Cancellazione di un Dominio Alias

DELETE /domains/#{domain_code}/alias_domains/#{alias_domain_code}

Il codice del dominio alias da cancellare può essere recuperato dalla lista dei domini alias.

risposta
{
   "status":206,
   "message":"No content needed"
}
Example
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/alias_domains/#{alias_domain_code}

Verifica della proprietà

Prima di poter attivare un dominio in Qboxmail devi dimostrare di esserne il proprietario o un incaricato alla sua gestione. Questo controllo è eseguito mediante la richiesta di inserire un record di tipo A nel DNS del dominio. Una volta recuperato il record con una chiamata alla lista dei domini (indicato alla voce possession_a_record), ed inserito nel DNS si può eseguire la chiamata per farlo controllare dal pannello di Qboxmail.

Eseguire una semplice richiesta come questa:

 

GET /domains/#{domain_code}/alias_domains/#{alias_domains_code}/ownership_check

In questo modo, se il codice è inserito correttamente, il pannello processerà la richiesta di attivazione del dominio il quale sarà disponibile a breve.

Abilitare/Disabilitare un dominio

I domini alias ereditano lo stato di attivo/disattivo del dominio reale a cui sono collegati.

Profili Dominio

Un Profilo Dominio è un template che definisce le caratteristiche che un dominio avrà disponibili al momento della sua creazione.

Struttura

  • name nome del profilo
  • is_default flag
  • max_email_accounts numero massimo di account email nel dominio (-1 no limits)
  • max_email_quota quota massima delle caselle email espressa in bytes (1,2,3,4,5,6,7,8 o 16 e 25 GB)
  • email_pop_disabled flag
  • email_webamil_disabled flag
  • email_imap_disabled flag
  • email_smtp_disabled flag

Creazione di un Profilo Dominio

POST /domains_plans

Eexempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domain_plans -d "name=standard&is_default=true&max_email_accounts=-1&max_email_quota=8589934592&email_pop_disabled=false&email_webmail_disabled=false&email_imap_disabled=false&email_smtp_disabled=false"

Lista dei Profili Dominio

GET /domains_plans

risposta
{
   ...
   "resources":[
      {
         "code":"DP81143666",
         "name":"standard",
         "is_default":true,
         "max_email_accounts":-1,
         "max_email_quota":"8589934592",
         "email_pop_disabled":false,
         "email_webmail_disabled":false,
         "email_imap_disabled":false,
         "email_smtp_disabled":false,
         "manager_plans_count":0
      }
   ],
   ...
   "status":200,
   "message":"Returned content"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/domain_plans 

Cancellazione di un Profilo Dominio

DELETE /domains_plans/#{domain_plan_code}

Puoi recuperare il codice del profilo dominio da cancellare dalla lista dei profili dominio

risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/domain_plans/#{domain_plans_code}

Dominio

In Qboxmail un dominio è l’entità all’interno della quale vengono aggiunte le caselle email ad esso associate. Va ricordato che un dominio prima di essere inserito nel pannello di Qboxmail deve già essere registrato, attivo e con la possibilità di gestire i suoi DNS.

Struttura

  • alias_domains_count numero di domini alias associati a questo dominio
  • alias_email_count numero di email alias associati agli account email di questo dominio
  • email_accounts_count numero di account email presenti in questo dominio
  • catch_all_activated true|false indica se l’opzione “catchall” può essere attivata o no
  • catch_all_destination indirizzo email destinatario delle “catchall” (uno solo)
  • catch_all_enabled true|false indica se la funzione catchall è abilitata o no
  • code: il codice identificativo del dominio
  • customer_code: il codice identificativo del cliente proprietario del dominio
  • Domain Names: lista dei domini associati a questo utente, concatenati
  • email_imap_disabled true|false
  • email_pop_disabled true|false
  • email_smtp_disabled true|false
  • email_webmail_disabled true|false
  • health_state string indica se i record MX del dominio sono configurati correttamente
  • max_email_accounts il numero massimo di account email che il dominio può avere (-1 no limits)
  • max_email_quota la quota massima espressa in bytes (1,2,3,4,5,6,7,8 o 16 e 25 GB)
  • max_mailing_lists il numero massimo di mailing-list che il dominio può avere (-1 no limits)
  • name nome del dominio
  • possession_a_record questo campo, valorizzato solo quando il dominio non è ancora attivo, indica il codice per la verifica della proprietà da inserire nel DNS del dominio. Trovi qui maggiori informazioni sulla verifica della proprietà del dominio
  • state lo stato del dominio, può essere active, disabled o blocked.
  • state_detail una spiegazione sullo stato corrente del dominio

Per un output completo della richiesta si veda in fondo alla pagina, i nomi dei campi sono autoesplicativi.

Creare un dominio

POST /domains

Parametri obbligatori
  • name
  • postmaster_password
  • postmaster_password_confirmation
  • max_email_accounts
  • email_imap_disabled
  • email_pop_disabled
  • email_smtp_disabled
  • email_webmail_disabled
  • catch_all_enabled
  • catch_all_activated
  • max_mailing_lists
risposta
{
   "status":201,
   "message":"New resource created"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains -d "name=mario.it&postmaster_password=12345&postmaster_password_confirmation=12345&email_smtp_disabled=false&email_webmail_disabled=false&email_pop_disabled=false&email_imap_disabled=false&max_mailing_lists=-1&catch_all_activated=false"

Modifica di un dominio

PUT /domains/#{domain_code}

Parametri obbligatori
  • name
  • postmaster_password
  • postmaster_password_confirmation
  • max_email_accounts
  • email_imap_disabled
  • email_pop_disabled
  • email_smtp_disabled
  • email_webmail_disabled
  • catch_all_enabled
  • catch_all_activated
  • max_mailing_lists
risposta
{
   "status":206,
   "message":"No content neeeded"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X put https://apimail.cbsolt.net/api/v1/domains -d "name=mario.it&postmaster_password=12345&postmaster_password_confirmation=12345&email_smtp_disabled=false&email_webmail_disabled=false&email_pop_disabled=false&email_imap_disabled=false&max_mailing_lists=-1&catch_all_activated=false"

Lista dei domini

GET /domains

risposta
{   ...
   "resources":[
      {
         "code":"D813085313",
         "name":"provacremona.io",
         "state":"enabled",
         "state_detail":"",
         "health_state":"unhealthy",
         "customer_code":"5504310233",
         "manager_codes":"",
         "customer_fullname":"Mario Benigni",
         "customer_fullname_with_code":"Mario Benigni [5504310233]",
         "possession_a_record":"",
         "max_email_accounts":-1,
         "max_email_quota":"8589934592",
         "email_pop_disabled":false,
         "email_webmail_disabled":false,
         "email_imap_disabled":false,
         "email_smtp_disabled":false,
         "max_mailing_lists":0,
         "catch_all_enabled":false,
         "catch_all_activated":false,
         "catch_all_destination":null,
         "alias_domains_count":0,
         "email_accounts_count":1,
         "alias_emails_count":0,
         "postmaster":{
            "code":"4207750225",
            "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":"",
            "autoresponder_enabled":false,
            "autoresponder_subject":null,
            "autoresponder_content":null,
            "max_email_quota":"52428800",
            "current_quota":0,
            "current_lastauth":"none",
            "preferred_timezone":3600,
            "preferred_language":"it"
         }
      },
      {
        ...
      },
      {
        ...
         }
      }
   ],
   "status":200,
   "message":"Returned content"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/domains

Cancellazione di un dominio

DELETE /domains/#{domain_code}

Il codice del dominio da cancellare può essere recuperato dalla lista dei domini.

risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/domains/#{domain_code}

Verifica della proprietà

Prima di poter attivare un dominio in Qboxmail devi dimostrare di esserne il proprietario o un incaricato alla sua gestione. Questo controllo è eseguito mediante la richiesta di inserire un record di tipo A nel DNS del dominio. Una volta recuperato il record con una chiamata alla lista dei domini (indicato alla voce possession_a_record), ed inserito nel DNS si può eseguire la chiamata per farlo controllare dal pannello di Qboxmail.

Eseguire una semplice richiesta come questa:

GET /domains/#{domain_code}/ownership_check

In questo modo, se il codice è inserito correttamente, il pannello processerà la richiesta di attivazione del dominio il quale sarà disponibile a breve.

Abilitare/Disabilitare un dominio

I domini di norma sono attivi. E’ possibile disabilitargli, anche temporaneamente. Una volta disabilitato un dominio gli account email non potranno più eseguire login sul sistema (ma i dati rimarranno immutati) e le email inviate al dominio saranno respinte con un messaggio di avviso.

Per disabilitare un dominio eseguire questa chiamata:

GET /domains/#{domain_code}/disable

e con questa chiamata è possibile riabilitarlo:

GET /domains/#{domain_code}/enable

Abilitare le caselle email da 25GB su un dominio

Se hai bisogno di più spazio per le tue caselle email puoi attivare l’opzione (a pagamento) che consente di espandere lo spazio delle singole caselle a 25GB.

Per attivare l’opzione su un dominio eseguire la seguente chiamata:

PUT /domains/#{domain_code}/

Parametri obbligatori
  • max_email_quota: “26843545600”
  • apply_to_children: true | false (true se volete variare la dimensione di tutte le caselle email del dominio portandola da subito a 25GB, false se volete variarle voi manualmente in maniera singola)

E’ possibile anche disattivare l’opzione da 25 GB e riportare la quota di tutte le caselle email ad 8GB a patto che nessuna delle caselle email abbia già superato questa quota, altrimenti è necessario riportarla sotto quella quota prima di poter eseguire la disattivazione:

PUT /domains/#{domain_code}

Parametri obbligatori
  • max_email_quota: “8589934592”
  • apply_to_children: true

ETLive

Analisi dei log del traffico email per accessi POP/IMAP, Antispam, Antivirus ed email inviate, in tempo reale.

Archivio Log Mail Inviate

Dopo un ora i Log delle Email Inviate (ed i codici di risposta dei server remoti) sono spostati nell’Archivio di ETLive e qui mantenuti per 14 giorni.

GET /mailouts_logs
Parametri
  • domain_code
  • email_account_code
  • page
  • date_to data nel formato Unix Timestamp. Qui un semplice tool per la conversione
  • selection
    • mailouts_clear : our antiviruses didn’t find risks
    • mailouts_temporary : these mail are temporary blocked (probably the volume is too high)
    • mailouts_spam_permanent : these mail are permanently blocked by the antispam/antivirus(omit this parameter for see all the mailouts)
Argomenti
domain_code string
email_account_code integer
page integer
date_to Unix timestamp

data nel formato Unix Timestamp. Qui un semplice tool per la conversione

selection
  • mailouts_clear : our antiviruses didn’t find risks
  • mailouts_temporary : these mail are temporary blocked (probably the volume is too high)
  • mailouts_spam_permanent : these mail are permanently blocked by the antispam/antivirus(omit this parameter for see all the mailouts)
Esempio di richiesta
$ curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/mailouts_logs?domain_code=D2666670063&email_account_code=4656663752&date_to=1200179100
Esempio di risposta
{
   "resources":[
      {
         "code":"AE36546336",
         "name":"luigi",
         "fullemail":"luigi@mario.io",
         "state":"enabled",
         "state_detail":"",
         "destination":"mario@mario.com"
      }
   ],
   ...,
   "status":200,
   "message":"Returned content"
}

Archivio Log Mail Ricevute

Dopo un ora i log delle email ricevute, ed il risultato della scansione antispam ed antivirus, vengono sopostati in Archivio e qui mantenuti per 14 giorni.

GET /mailins_logs

Parametri
  • domain_code
  • email_account_code
  • page
  • date_to data nel formato Unix Timestamp. Qui un semplice tool per la conversione
  • selection
    • mailins_clear : la scansione antivirus non ha rilevato rischi
    • mailins_virus : la scansione antivirus ha rilevato un rischio
    • mailins_spam_tagged : l’email è stata marcata come probabile spam
    • mailins_spam_rejected : l’email è stata marcata come spam e respinta

    (omettendo questo parametro si possono vedere tutte le email ricevute)

Esempio
curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/mailins_logs?domain_code=D2666670063&email_account_code=4656663752&date_to=1200179100

Archivio Log Accessi

Dopo un ora i log degli accessi ed errori POP/IMAP/Webmail vengono spostati in Archivio e qui mantenuti per 14 giorni.

GET /accesses_logs

Parametri
  • domain_code
  • email_account_code
  • page
  • date_to data nel formato Unix Timestamp. Qui un semplice tool per la conversione
  • selection accesses_errors
Esempio
curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/accesses_logs?domain_code=D2666670063&email_account_code=4656663752&date_to=1200179100
Argomenti
domain_code string

Il codice dominio

email_account_code string

Codice account email

page integer
date_to Unix Timestamp

data nel formato Unix Timestamp. Qui un semplice tool per la conversione

selection

accesses_errors

Log in tempo reale

I log in tempo reale mostrano gli eventi (accessi ed errori POP/IMAP/Webmail, email inviate e ricevute) dell’ultima ora.

GET /real_time_logs

Parametri
  • domain_code
  • email_account_code
  • page
  • selection mailouts | mailins | accesses | accesses_errors | mailouts_queued | accesses_openeds (currently logged in users)
  • timewindow last_#{number_of_minutes}_minutes. number_of_minutes = 5 | 10 | 15 | 30 | 60

risposta

{
   "resources":[
      {
         "i":"3lbjdg3FDqzXTP",
         "w":00000000,
         "h":"smtp2",
         "p":"66",
         "cn":"00-000-000-00.v4.ngi.it",
         "ci":"00.000.000.00",
         "m":"PLAIN",
         "u":"mario.rossi",
         "d":"qboxmail.com",
         "mi":"000000.0000000@qboxmail.com",
         "s":" etlive ",
         "f":"mario.rossi@qboxmail.com",
         "b":999,
         "r":1,
         "de":[
            {
               "w":000000,
               "h":"gmail-smtp-in.l.google.com[173.194.67.27]:25",
               "r":"mario.giallo@gmail.com",
               "d":"2.1",
               "n":"2.0.0",
               "s":"sent",
               "t":"(250 2.0.0 OK 0000000 wj10si23413303wjb.0 - gsmtp)"
            }
         ]
      }
   ],
   "filters":{
      "page":"1",
      "selection":"mailouts"
   },
   "status":200,
   "message":"Returned content"
}
Esempio
curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1//real_time_logs?domain_code=D265666063&email_account_code=4654888752&selection=mailouts&timewindow=last_30_minutes&page=1

Utenti

Come gestire le varie utenze ed i livelli di accesso nel pannello di controllo di Qboxmail.

Postmaster

L’utente postmaster può gestire solamente il suo dominio e creare un numero di caselle email limitato a quanto indicato da Customer o dal Manager per lo specifico dominio. L’utente postmaster@DOMINIO è creato automaticamente ogni volta che si attiva un nuovo dominio.

Cambiare la password del postmaster

PUT /domains/#{domain_code}/postmaster

Parametri
  • email_password : password
  • email_password_confirmation: password confirmation
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/domains/#{domain_code}/postmaster -d "email_password=#{new_pass}&email_password_confirmation=#{new_pass}"

Profili Manager

Un profilo manager è un template che definisce il tipo di risorse che un manager ha a disposizione quando attiva un dominio o il numero massimo di domini che può attivare.

Creazione di un Profilo Manager

POST /manager_plans

Parametri
  • name: the name of the manager plan
  • is_default: flag
  • max_domains: number of maximum domains that the manager can have (-1 for no limits)
  • domain_plan_codes the identifier code of the domain plan
risposta
{
   "status":201,
   "message":"New resource created"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/manager_plans -d "name=standard&is_default=true&max_domains=-1&domain_plans_codes=89829324"

Lista dei Profili Manager

GET /manager_plans

risposta
{
   ...
   "resources":[
      {
         "code":"MP24333866",
         "name":"Ben",
         "is_default":true,
         "max_domains":-1,
         "domain_plan_codes":"DP46037338",
         "managers_count":0,
         "domain_plans_count":1
      }
   ],
   ...
   "status":200,
   "message":"Returned content"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/manager_plans 

Cancellare un Profilo Manager

DELETE /manager_plans/#{manager_plan_code}

Devi prima recuperare il codice del profilo che vuoi cancellare dalla lista dei profili.

risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/manager_plans/#{manager_plans_code}

Manager

Il manager è uno speciale utente a cui si può assegnare la gestione di un certo numero di domini. Ricordiamo che per gestire il singolo dominio è sempre presente l’utente postmaster@DOMINIO che viene creato nel momento dell’attivazione del dominio.

Struttura

  • Code: the identifier code of the customer
  • Manager Plan Code: the identifier of the manager plan
  • Domain Names: list of all domains of the user, concatenated
  • Email: email address
  • firstname
  • lastname
  • company
  • fullname_with_code:string that concatenates firstname and lastname and code
  • max_domains: number of maximum domains that the customer can activate
  • max_email_quota: maximun email quota in bytes. (1,2,3,4,5,6,7 or 8 GB)…

Per l’output completo vedere in fondo alla pagina, i nomi dei campi sono tutti autoesplicativi.

Creare un manager

POST /managers

Parametri
  • firstname
  • lastname
  • email
  • company
  • manager_plan_code
  • domain_names
  • password
  • password_confirmation
risposta
{
   "status":201,
   "message":"New resource created"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/manager -d "firstname=mario&lastname=rossi&email&mario@rossi.eu&manager_plan_code=3239324&password=12345&password_confirmation=12345"

Modificare un manager

POST /managers/#{manager_code}

Parametri
  • firstname
  • lastname
  • email
  • company
  • manager_plan_code
  • domain_names
  • password
  • password_confirmation
risposta
{
   "status":206,
   "message":"No content neeeded"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X post https://apimail.cbsolt.net/api/v1/manager/2121334 -d "firstname=mario&lastname=rossi&email&mario@rossi.eu&manager_plan_code=3239324&password=12345&password_confirmation=12345"

Ottenere la lista dei manager

GET /managers

risposta
{
   ...
   "resources":[
      {
         "code":"0140101157",
         "manager_plan_code":"MP5533866",
         "domain_names":"qboxmail.com",
         "email":"email@email.com",
         "firstname":"mario",
         "lastname":"rossi",
         "company":"",
         "fullname":"Mario Rossi",
         "fullname_with_code":"Mario Rossi [0140101157]",
         "max_domains":-1,
         "max_email_quota":"8589934592",
         "domains_count":1,
         "alias_domains_count":0,
         "email_accounts_count":1,
         "alias_emails_count":0,
         "catch_alls_count":0,
         "preferred_timezone":3600,
         "preferred_language":"it"
      }
   ],
   ...
   "status":200,
   "message":"Returned content"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X get https://apimail.cbsolt.net/api/v1/managers

Cancellare un manager

DELETE /managers/#{manager_code}

Devi prima ottenere il codice del manager che vuoi cancellare recuperando la lista dei manager.

risposta
{
   "status":206,
   "message":"No content needed"
}
Esempio
    curl -H "X-API-TOKEN:XXXXXXXXX" -X delete https://apimail.cbsolt.net/api/v1/managers/#{manager_code}

Customer

In Qboxmail il tipo di utente Customer è il cliente che ha acquistato il servzio, ed ha quindi i massimi privilegi nel pannello di controllo.

Di seguito i dettagli della struttura della risorsa “customer” accessibile e modificabile mediante una chiamata REST:

  • Code: the identifier code of the customer
  • Customer Plan Code: the identifier of the current payment plan
  • Domain Names: list of all domains of the user, concatenated
  • Email: email address
  • firstname
  • lastname
  • company
  • address
  • zip
  • city
  • zone
  • cf fiscal code, for Italian and Europeans
  • vat VAT code for companies
  • country
  • phone
  • is_a_company: true/false flag
  • fullname_with_code: string that concatenates firstname and lastname and code
  • max_domains: number of maximum domains that the customer can activate
  • max_email_accounts: number of maximum email accounts that the customer can activate
  • max_mailing_lists: number of maximum mailing lists that the customer can activate
  • max_catch_all: number of maximum mailing lists that the customer can activate
  • max_email_quota: maximum email quota in bytes. (1,2,3,4,5,6,7 or 8 GB)
  • counters: various counters of the data linked to this account, like managers, domains, alias_domains

Per ottenere l’output completo dei dettagli di un account customer utilizzare la seguente chiamata. Verranno anche riportati tutti i domini associati a questo utente.

GET /customers

 

ecco la risposta del server:

{
   "resources":[
      {
         "code":"5604310278",
         "customer_plan_code":"CP17160475",
         "domain_names":"qboxmail.it,provacremona.io",
         "email":"fvbenigni@gmail.com",
         "firstname":"Mario",
         "lastname":"Benigni",
         "company":null,
         "address":"",
         "zip":"",
         "city":"",
         "zone":null,
         "cf":null,
         "vat":null,
         "country":null,
         "phone":"",
         "is_a_company":false,
         "general_terms_and_conditions_approved":false,
         "unfair_terms_approved":false,
         "privacy_policy_approved":false,
         "has_billing_details":false,
         "fullname":"Mario Benigni",
         "fullname_with_code":"Mario Benigni [5604310278]",
         "can_have_managers":false,
         "max_domains":10,
         "max_email_accounts":25,
         "max_mailing_lists":0,
         "max_catch_alls":0,
         "max_email_quota":"8589934592",
         "domain_policy":"accept",
         "manager_plans_count":0,
         "domain_plans_count":0,
         "managers_count":0,
         "domains_count":2,
         "alias_domains_count":0,
         "email_accounts_count":1,
         "alias_emails_count":0,
         "mailing_lists_count":0,
         "catch_alls_count":0,
         "preferred_timezone":3600,
         "preferred_language":"it"
      }
   ],
   ...
   "status":200,
   "message":"Returned content"
}

Molti di questi dati hanno solo valenza informativa e non possono essere modificati.