## SMTPBackend


An SMTP backend submits each message to an SMTP server through `smtplib`.


Usage

``` python
SMTPBackend(
    host, *, port=587, security="starttls", from_address, credential=None
)
```


[connect()](Backend.md#epistole.Backend.connect) opens the socket, starts TLS unless `security` is `"none"`, and authenticates. So a wrong password or a rejected token raises [AuthenticationError](exceptions.AuthenticationError.md#epistole.exceptions.AuthenticationError) on that line. Every socket operation times out after 60 seconds, and no setting changes it. See ADR-0005 and ADR-0017.

A server may refuse some recipients and accept the rest. The send then returns normally with the refusals in `SendResult.refused`, so a caller who ignores the send result loses them. See ADR-0004.

There is no size pre-check. `smtplib` sends the message size to a server that advertises `SIZE`, and the server's `552` raises [RejectedError](exceptions.RejectedError.md#epistole.exceptions.RejectedError). See ADR-0019.


## Parameters


`host: str`  
The server's host name. TLS checks the server's certificate against it.

`port: int = ``587`  
Pass 465 with `security="tls"`, because 587 is the STARTTLS port.

`security: Literal[``"starttls", `<span class="st">`"tls"``, ``"none"``]`</span>` = ``"starttls"`  
`"starttls"` upgrades after EHLO and raises [TransportError](exceptions.TransportError.md#epistole.exceptions.TransportError) when the server does not offer it. `"tls"` starts TLS on connect. `"none"` sends in plaintext, a password included. There is no opportunistic mode, and nothing infers the mode from the port.

`credential: Password | OAuth | None = None`  
`None` submits anonymously. A [Password](smtp.Password.md#epistole.smtp.Password) authenticates through PLAIN, LOGIN or CRAM-MD5, and an [OAuth](smtp.OAuth.md#epistole.smtp.OAuth) authenticates with an access token through XOAUTH2.


## Raises


`TypeError`  
When `credential` is none of [Password](smtp.Password.md#epistole.smtp.Password), [OAuth](smtp.OAuth.md#epistole.smtp.OAuth) and `None`.

`ImportError`  
When an [OAuth](smtp.OAuth.md#epistole.smtp.OAuth) holds a Graph or Gmail value, and that backend's extra is not installed.

`ValueError`  
When `security` is not one of the three modes.