SendMail - API per l'accodamento di messaggi di posta elettronica

Endpoind: https://api.amecom.it/sendmail/send

Introduzione

Lo scopo della API è creare un interfaccia astratta, condivisa e stabile per l'invio di posta elettronica.

L'API è progettata per riceve dati in formato JSON, secondo lo schema descritto. I messaggi vengono inseriti in una coda di invio e quindi spediti per posta elettronica ai destinatari.

L'utilizzo di questa API è permesso solo ad HOST ACCREDITATI. Per rircaricare la lista degli HOST chiamare https://api.amecom.it/sendmail/reload_whitelist

Schema file JSON

Il file JSON che descrive un messaggio è formato dalle seguenti proprietà

Properità	Obbligatorio	Default	Descrizione
delivery	SI		Informazioni sulle modalità di invio.
delivery.allow_duplicates	NO	`false`	Il sistema prevede che email i cui campi from.address, to.address, message.subject e delivery.app sono uguali in un arco temporale (variabile secondo impostazioni) vengano inviate una volta sola evitando l'invio di duplicati. È possibile evitare questo comportamento, quindi permettere l'invio di duplicati, impostando questa proprietà su `true`.
delivery.allow_reply	NO	`true`	Se impostato a `false` viene impedito il reply al messaggio tramite l'header: 'Return-Path' = "<>"
delivery.app	SI		Nome dell'applicazione che invia il messaggio.
delivery.datesend	NO	now	Questa proprietà può essere utilizzata per posticipare l'invio della email dopo una certa data. Il formato della data è YYYYMMDDHHMMSS il fuso orario deve essere UTC. Se non viene specificata la data o inserita una data nel passato il messaggio verrà inviata il prima possibile.
delivery.msgid_domain	NO		Permette di specificare il dominio per la generazione del header `Message-Id` dell'email. Se non specificato viene generato automaticamente dal sistema.
delivery.priority	NO	`10`	La priorità è utilizzanta internamente per indicare la priorità di invio nella coda messaggi. Il valore è compreso tra `0` e `255`, dove un valore maggiore ha priorità su un valore minore. Tra i valori possibili il valore 0 ha un significato speciale: le email con priorità = 0 sono inviate aggiungendo i seguenti attibuti: 'Precedence'= "bulk"
from	SI		Dizionario contenente le proprietà del mittente. Il mittente dovrebbe essere un account conosciuto dal server di posta elettronica.
from.address	SI		Indirizzo email del mittente.
from.name	NO		Nome visualizzato del mittente, se omesso corrisponde a from.address.
message	SI		Dizionario contenente le informazioni del messaggio.
message.alternate_text	NO	CONVERSIONE AUTOMATICA	Se il message.body è in formato HTML (message.body_is_html=True) è possibile specificare un testo alternativo in formato solo testo tramite questa proprietà. Se non viene inserito un testo alternativo avviene una conversione automatica. Se il message.body è in solo testo (message.body_is_html=False) questo campo viene ignorato.
message.body	SI		Corpo della email in formato HTML o TESTO.
message.body_is_html	NO	`false`	Se questa proprietà non viene impostata o viene impostata su `false` si presume che il message.body sia testo semplice. Se il message.body è in formato HTML è necessario indicarlo impostando questa proprietà su `true`.
message.list_unsubscribe	NO		Se l'applicazione che invia le email prevede un url da cui è possibile bloccare la ricezione di ulteriori email qui è possbile inserire la url. In ogni caso è sempre necessario includere il link a questa pagina anche nel corpo della email.
message.reference_id	NO		Se l'email è una risposta a un altro messaggio è possibile inserire qui l'id del messaggio originale. L'ID del messaggio NON DEVE CONTENERE i caratteri < e >.
message.subject	SI		Oggetto della email.
to	SI		Dizionario contenente le proprietà del destinatario.
to.address	SI		Indirizzo email del destinatario.
to.name	NO		Nome visualizzato del destinatario, se omesso corrisponde a to.address.

Risposta della API

La risposta della API informa se il messaggio è stato aggiunto alla coda eseguendo una verifica formale delle proprietà impostate. Non verifica che il messaggio sia effetivamente stato inviato o se è un duplicato.

In caso di successo l'API risponde

{
    "status":200,
    "message_id": IDMESSAGGIO
}

In caso di errore:

{
    "status":500,
    "error": ["messaggio", "messaggio"]
}

Può essere eseguito un controllo veloce sullo stato del messaggio senza acedere al file JSON di risposta attraverso lo status code della richiesta HTTP.

Inserire un messaggio alla coda

Per inserire un messaggio in coda di invio occorre inviare una richiesta POST al url /sendmail/send inserendo un file JSON negli Header

Esempio Python


import requests
data = {
    "from" :{
        "address": "mittente@esempio.it"
        },
    "to" : {
        "address" : "destinatario@esempio.it"
        },
    "message" : {
        "subject": "Oggetto email",
        "body": "Corpo del messaggio"
        },
    "delivery":{
        "app": "NOME APPLICAZIONE"
        }        
}
response = requests.post("https://api.amecom.it/sendmail/send", json=data, timeout=3)
result = response.json()