11.12.1 Oggetti SMTP

Un'istanza SMTP possiede i seguenti metodi:

set_debuglevel( level): Imposta il livello di informazioni di debug. Un valore reale per level riporta tutte le informazioni di connessione per tutti i messaggi inviati e ricevuti dal server.

connect( [host[, port]]): Si connette ad un host su di una porta port indicata. Predefinitamente si connette all'host locale sulla porta standard SMTP (25). Se l'hostname termina con i due punti (":") seguiti da un numero, questo suffisso verrà estrapolato ed il numero interpretato come la porta da utilizzare. Questo metodo viene automaticamente invocato dal costruttore se un host viene specificato durante la creazione dell'istanza.

docmd( cmd, [, argstring])

Invia un comando cmd al server. L'argomento opzionale argstring è semplicemente concatenato al comando, separato da uno spazio.

Restituisce una doppia tupla composta da un codice di risposta numero e una riga della risposta attuale (risposte multiriga sono sommate in una singola lunga riga).

Nelle normali operazioni non dovrebbe essere necessario chiamare questo metodo esplicitamente. Viene usato per implementare altri metodi e può tornare utile per testare estensioni private.

Se viene persa la connessione al server durante l'attesa della risposta viene sollevata l'eccezione SMTPServerDisconnected.

helo( [hostname]): Identifica sé stesso al server SMTP utilizzando "HELO". L'argomento predefinito dell'hostname è il nome di dominio completo e pienamente qualificato dell'host locale.
Nelle normali operazioni non dovrebbe essere necessario chiamare questo metodo esplicitamente. Viene implicitamente chiamato da sendmail() quando necessario.

ehlo( [hostname]): Identifica sé stesso ad un server ESMTP utilizzando "EHLO". L'argomento predefinito dell'hostname è il nome di dominio completo e qualificato dell'host locale. Esamina la risposta per le opzioni ESMTP e le memorizza per utilizzarle poi con has_extn().
Finché si desidera usare has_extn() prima di inviare mail, non dovrebbe essere necessario usare questo metodo esplicitamente. Verrà chiamato implicitamente da sendmail() quando necessario.

has_extn( name): Restituisce True se name è nell'insieme delle estensioni del servizio SMTP restituito dal server, altrimenti False. Le differenze tra maiuscole e minuscole verranno ignorate.

verify( address): Verifica la validità dell'indirizzo sul server usando il comando SMTP "VRFY". Restituisce una tupla consistente nel codice 250 ed un indirizzo perfettamente rispondente all'RFC 822 (compreso il nome umano) quando l'indirizzo dell'utente è valido. Altrimenti restituisce un codice di errore SMTP 400 o maggiore, ed una stringa di errore.
Note: Molti siti disabilitano il comando SMTP "VRFY" per evitarne l'utilizzo da parte degli spammers.

login( user, password)

Accede ad un server SMTP che richiede l'autenticazione. Gli argomenti sono username e password con cui autenticarsi. Se in questa sessione, precedentemente, non c'è stato un comando "EHLO" o "HELO", il metodo prova prima il comando ESMTP "EHLO". Questo metodo abitualmente terminerà correttamente se l'autenticazione ha avuto successo, o solleverà le seguenti eccezioni:

SMTPHeloError: Il server non risponde adeguatamente all'invito "HELO".
SMTPAuthenticationError: Il server non accetta la combinazione nome-utente/password.
SMTPError: Non sono stati trovati metodi di autenticazione accettabili.

starttls( [keyfile[, certfile]]): Mette la connessione SMTP in modalità TLS (Transport Layer Security). Tutti i comandi SMTP che seguono saranno criptati. Dovrete chiamare ehlo() nuovamente.
Se vengono forniti keyfile e certfile, questi vengono passati alla funzione ssl() del modulo socket.

sendmail( from_addr, to_addrs, msg[, mail_options, rcpt_options])

Invia la mail. Gli argomenti richiesti sono una stringa RFC 822 from-address, una lista di indirizzi RFC 822 to-address, ed una stringa col messaggio. Il chiamante può passare una lista di opzioni ESMTP (come "8bitmime") da usare nel comando "MAIL FROM"come mail_options. Le opzioni ESMPT (come il comando "DSN") che dovrebbero essere usate con tutti i comandi "RCPT" possono essere passate come rcpt_options. Se avete bisogno di usare opzioni ESMTP differenti per ciascun destinatario, dovete usare un metodo di più basso livello come mail, rcpt e data per inviare il messaggio.

Note: I parametri from_addr e to_addrs vengono usati per costruire l'intestazione del messaggio usata dall'agente di trasporto. La classe SMTP non modifica le intestazioni del messaggio in nessun modo.

Se in questa sessione non ci sono stati precedenti comandi "EHLO"o "HELO", questo metodo prova per prima cosa il comando ESMTP "EHLO". Se il server supporta ESMTP, la dimensione del messaggio ed ognuna delle opzioni specificate gli verranno passate (se l'opzione è nell'insieme di particolarità specificate dalle indicazioni inviate dal server stesso). Se "EHLO" fallisce, verrà tentato "HELO" ed il supporto ESMTP verrà soppresso.

Questo metodo terminerà regolarmente se la mail viene accettata per almeno un destinatario. Altrimenti solleverà un'eccezione. In parole povere, se non c'è un'eccezione, qualcuno riceverà la mail. Se questo metodo non solleva un'eccezione, restituirà un dizionario, con una riga per ogni destinatario rifiutato. Ogni riga contiene una tupla del codice di errore SMTP ed il messaggio di errore corrispondente inviato dal server.

Questo metodo può sollevare le seguenti eccezioni:

SMTPRecipientsRefused: Tutti i destinatari sono stati rifiutati. Nessuno riceverà mail. L'attributo recipients dell'oggetto dell'eccezione è un dizionario contenente le informazioni circa i destinatari rifiutati (come quello restituito quando almeno uno dei destinatari è stato accettato).
SMTPHeloError: Il server non risponde propriamente al comando "HELO".
SMTPSenderRefused: Il server non accetta from_addr.
SMTPDataError: Il server risponde con un codice di errore inatteso (diverso da quello di un destinatario rifiutato).

Diversamente da quanto altrimenti fatto notare, la connessione resterà aperta dopo che un'eccezione è stata sollevata.

quit( ): Termina la sessione SMTP e chiude la connessione.

Vengono anche supportati i metodi di basso livello che corrispondono ai comandi standard SMTP/ESMTP "HELP", "RSET", "NOOP", "MAIL", "RCPT" e "DATA". In condizioni normali non c'è bisogno di chiamare questi metodi direttamente, e quindi non sono qui documentati; consultare il codice del modulo.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.