## GmailBackend


A Gmail backend sends each message through the Gmail API's `messages.send`, as the RFC 5322 message SMTP would write.


Usage

``` python
GmailBackend(
    *,
    from_address,
    credential,
)
```


[connect()](Backend.md#epistole.Backend.connect) reads the credential's file, builds one HTTP client, and gets an access token. So a rejected credential raises [AuthenticationError](exceptions.AuthenticationError.md#epistole.exceptions.AuthenticationError) on that line. A token request makes one attempt, and a failure on Google's side raises [ProviderError](exceptions.ProviderError.md#epistole.exceptions.ProviderError) there. It sends nothing to the Gmail API, so a token without the scope raises on the first send instead. Every request times out after 60 seconds, and no setting changes it. See ADR-0005 and ADR-0009.

Epistole requests the scope `https://www.googleapis.com/auth/gmail.send` alone, which grants no right to read or delete messages. See ADR-0011.

Before writing, a send raises [RejectedError](exceptions.RejectedError.md#epistole.exceptions.RejectedError) for more than 500 recipients, or for a message over 36,700,160 bytes once encoded. Both limits are Google's. See ADR-0019.

Gmail accepts or refuses the whole message, so `SendResult.refused` is always empty.

Gmail replaces the `Message-ID` Epistole sets with its own. When [from_address](Backend.md#epistole.Backend.from_address) is neither the account nor one of its verified aliases, Gmail sends from the account's own address and raises nothing. `docs/research/live-send-findings.md` records both.


## Parameters


`credential: ServiceAccount | AuthorizedUser | TokenCredential`  
Epistole calls a [TokenCredential](TokenCredential.md#epistole.TokenCredential)'s [get_token](TokenCredential.md#epistole.TokenCredential.get_token) with the `gmail.send` scope before each request.


## Raises


`TypeError`  
When `credential` is none of the three.

`ImportError`  
When `epistole[gmail]` is not installed.