thirdshift email-test through Resend #113

Parent

#109

What to build

thirdshift email-test [<address>] sends a test email through Resend's HTTP API, so the user can check their setup without starting a Run. It uses the same checks and the same sending code that Run notifications will use (ADR 0005). Resend accepting the message is all the command can verify.

Settings. The User config gains an [email] section with to and from, both optional. from defaults to onboarding@resend.dev, which Resend only lets send to the address of the user's own Resend account. The address is the command's argument, else email.to. The API key comes only from the RESEND_API_KEY environment variable, never from the config.

Checks before sending. These are local only; nothing is sent to validate the key. If no address is known, or RESEND_API_KEY is unset or empty, the command exits non-zero with a message naming what's missing and sends nothing.

Sending. One HTTPS POST to Resend's send-email endpoint, with a bearer token and a JSON body holding from, to, subject and a plain-text body. It goes over reqwest with rustls, which is already in the dependency tree. OpenSSL must never be pulled in (ADR 0003). The send has a bounded timeout of around 30 seconds.

The test email. Its subject is clearly marked as a test. Its body shows the hostname (from the OS, falling back to "unknown host"), the time and the sender used.

Output.

• On success: prints "accepted by Resend; check your inbox" and exits 0.
• On failure: prints Resend's error text word for word and exits non-zero.

Test seam. The Resend base URL can be overridden with the environment variable THIRDSHIFT_RESEND_URL, for tests only; it isn't documented for users. The harness gains a Resend stand-in: a small local HTTP server, using only the standard library, that records each request (method, path, authorization header, JSON body) and replies with a status and body the test chooses. The scenario points THIRDSHIFT_RESEND_URL at it.

Help lists email-test. The README documents email.to, email.from, RESEND_API_KEY, the onboarding@resend.dev restriction and email-test.

Acceptance criteria

• email-test <address> posts one request to the stand-in, with Authorization: Bearer <RESEND_API_KEY>, to set to that address, from set to onboarding@resend.dev by default, a subject marked as a test, and a body with hostname, time and sender
• email-test with no argument sends to email.to, and an argument wins over email.to
• email.from in the config replaces the default sender
• With no address known, it exits non-zero naming the missing address, and the stand-in receives nothing
• With RESEND_API_KEY unset or empty, it exits non-zero naming RESEND_API_KEY, and the stand-in receives nothing
• When the stand-in replies 2xx, it prints "accepted by Resend; check your inbox" and exits 0
• When the stand-in replies 401 or 500, it prints the reply's error text word for word and exits non-zero
• An unknown key in [email] is still rejected, as for the rest of the config
• The release build still has no OpenSSL dependency
• Help text and README document email-test and the email settings

Blocked by

• User config, with merge.always and --no-merge #111