## Connection


A connection is one live link a backend opened, for many sends until it closes for good.


Usage

``` python
Connection(
    backend,
    transport,
)
```


Build one with [Backend.connect()](Backend.md#epistole.Backend.connect). It belongs to one thread and one `with`, and never reopens. It checks each message and builds the submission and the send result, so a third-party backend writes only a [Transport](Transport.md#epistole.Transport). See ADR-0005.


## Attributes


`backend: Backend`  
The backend that opened this connection.


## Methods

| Name | Description |
|----|----|
| [__enter__()](#__enter__) | Return this connection, which [connect()](Backend.md#epistole.Backend.connect) already opened. |
| [__exit__()](#__exit__) | Close the connection, suppressing nothing. |
| [close()](#close) | Close the link for good. |
| [send()](#send) | Check `message`, submit it, and build the send result. |

------------------------------------------------------------------------


#### \_\_enter\_\_()


Return this connection, which [connect()](Backend.md#epistole.Backend.connect) already opened.


Usage

``` python
__enter__()
```


##### Raises


`ValueError`  
When the connection is closed.


------------------------------------------------------------------------


#### \_\_exit\_\_()


Close the connection, suppressing nothing.


Usage

``` python
__exit__(*exc_info)
```


------------------------------------------------------------------------


#### close()


Close the link for good.


Usage

``` python
close()
```


It is idempotent and never raises, so [__exit__](Connection.md#epistole.Connection.__exit__) never replaces an error from the `with` body. See ADR-0005.


------------------------------------------------------------------------


#### send()


Check `message`, submit it, and build the send result.


Usage

``` python
send(message)
```


When the service refuses some recipients and accepts the rest, the send raises nothing and `SendResult.refused` holds the refusals.


##### Raises


`ValueError`  
When the connection is closed, when the message names no recipient, or when an `<img src>` names a `cid:` that no inline image holds. When a `Message-ID` cannot hold the from address's domain, such as a domain with an empty label. See ADR-0015.

`RecipientsRefusedError`  
When the service refused every recipient.

`EpistoleError`  
The error the transport raised, with `backend` set.