Gmail email provider

Gmail provider sending through Google's SMTP relay (smtp.gmail.com:587) with app-password authentication.

Overview

Despite the name, this provider is not the Gmail API or OAuth2. It is a thin wrapper around SMTP submission to smtp.gmail.com:587, authenticated with a Google account username and an app-specific password. The provider negotiates the SMTP AUTH mechanism with the server (SMTPAuthAutoDiscover) instead of pinning one. It exists because Gmail and Google Workspace are a source of a working SMTP sender for hobby projects, internal tools, and prototyping. Most developers already have a Gmail account, and generating an app password is a short round-trip in the account settings.

Gmail enforces per-account daily send limits (around 500/day for personal accounts, around 2,000/day for Workspace). It throttles, suspends, or shadow-blocks accounts that look like they are sending bulk transactional traffic. In front of those caps, the provider applies its own client-side throttle of 5 calls per second with a burst of 10. The throttle gates every send and keeps the account below Gmail's anti-bulk heuristics. Treat this as a starter sender for development and small internal tools, not a production transactional path.

The provider implements the same EmailProviderPort as every other piko sender, so swapping Gmail for SES or Postmark is a one-line change. It validates Username and Password are non-empty at construction time. FromEmail defaults to the username if empty.

Requirements

A Google account (personal Gmail or Google Workspace).
An app password generated for the account. Account-level password does not work, Google requires an app password for SMTP submission with 2-step verification, and accounts without 2-step verification cannot create app passwords (so you must enable 2-step first).
Network egress to smtp.gmail.com:587.

Configuration

import (
    "context"
    "os"

    "piko.sh/piko/wdk/email/email_provider_gmail"
)

provider, err := email_provider_gmail.NewGmailProvider(ctx, email_provider_gmail.GmailProviderArgs{
    Username:  "[email protected]",         // required; the Google account address
    Password:  os.Getenv("GMAIL_APP_PWD"), // required; app password (16 chars, no spaces)
    FromEmail: "[email protected]",         // defaults to Username if empty
})
if err != nil {
    return err
}

NewGmailProvider accepts a trailing ...email_domain.ProviderOption variadic, but piko keeps the rate-limit option constructors unexported. The 5 calls per second throttle is therefore fixed for this provider, and your code cannot raise or disable it.

Bootstrap

ssr := piko.New(
    piko.WithEmailProvider("gmail", provider),
    piko.WithDefaultEmailProvider("gmail"),
)

Behaviour

Bulk sends are sequential. Gmail SMTP has no native batch API, so SendBulk loops over each message and calls Send one at a time. Every call passes through the 5 calls per second throttle. A failed message does not abort the batch. The provider gathers all failures into a single error.
Health probe. The provider answers piko's readiness and liveness checks. Readiness reports unhealthy when the username or password is missing, so a misconfiguration surfaces in the probe instead of at the first send.
Send metrics. Each send records OpenTelemetry counters and a duration histogram, tagged by status and send type, with no extra wiring.