SendGrid email for GoCommerce

What it does

Configuration

Two settings are required: the API key and the from address. Set them in Config from your own main(), or leave Config empty and fill them in under Notifications › Setup Email.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Create a key and a senderIn SendGrid: an API key with Mail Send permission, and a sender address SendGrid has verified.
2. Install the moduleImport it and pass sendgrid.New to gocommerce.New, as below — or run the reference binary with -sendgrid, which reads SENDGRID_API_KEY, SENDGRID_FROM and SENDGRID_FROM_NAME.
3. Give it bothKey and sender in Config, which starts it switched on, or under Notifications › Setup Email. A value typed into the panel counts on the next message, with no restart.
4. Edit the wordingSubjects and bodies are the engine’s templates, edited under Notifications › Setup Email. Place an order and the confirmation goes out.

import (
	"os"

	"github.com/itswadesh/gocommerce/core"
	sendgrid "github.com/itswadesh/gocommerce/ext/notify-sendgrid"
)

app, err := gocommerce.New(cfg,
	sendgrid.New(sendgrid.Config{
		APIKey: os.Getenv("SENDGRID_API_KEY"),
		From:   "orders@example.com",
	}),
)

How it works

• The engine’s words

  Subject and body come from the engine’s templates at send time — the panel’s edit if there is one, Config’s Subjects and Bodies if not, the engine’s default otherwise — rendered with Go’s text/template over the event’s flat data.

• Idle until complete

  Without both a key and a sender the module does not count as configured. The engine skips it, and the message goes to the log instead.

• Rejections settle, outages retry

  A 4xx other than 429 is logged and settled: a bad address will be rejected again. Unreachable, 429 or 5xx is returned as an error, and the engine retries the notification with backoff.

• Overrides checked at boot

  A Subjects or Bodies template that does not parse stops the store booting, rather than failing on the first sale.

• Only events with wording

  An event with no email template is skipped, not an error, so another module can add events this one has never heard of.

• Settings without a restart

  The panel’s values are read on every send and win over Config. The engine keeps a row per message in its notification log, and an operator can resend one from there.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• Plain text onlyEach email is sent as text/plain. There is no HTML body, no attachment and no SendGrid dynamic template.
• Amounts in minor unitsThe engine hands templates totals in minor units — 49900, not 499.00 — and a store that wants them formatted edits the template.
• Two backends, two emailsEvery configured email backend gets every message. With SendGrid and Resend both switched on, a shopper gets two; and a retry after one fails re-sends through both.
• Refusals count as sentA message SendGrid refuses returns no error, so the engine’s notification log records it as sent. The refusal is only in the application log.
• No successful-send log lineUnlike the Resend module, a message SendGrid accepts leaves no line in the application log; the engine’s notification log is the record.
• No bounce trackingThe module registers no webhook. Bounces, complaints and opens stay in SendGrid.