GmailBackend

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

Usage

Source

GmailBackend(
    *,
    from_address,
    credential,
)

connect() reads the credential’s file, builds one HTTP client, and gets an access token. So a rejected credential raises AuthenticationError on that line. A token request makes one attempt, and a failure on Google’s side raises 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 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 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’s 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.