Oko
Oko/Docs

Command reference

oko contact mail set

Declares the provider Oko mails asks through itself, for the `mail` channel on a machine without Stado: the provider's send endpoint (a Resend-compatible `POST` taking `from`, `to`, `subject` and `text`), the sender, the destination and an owner-only file holding the key. Nothing of it is guessed, and the key file is checked now, before anything is written.

Invocation#

Command
oko contact mail set --endpoint URL --from ADDRESS --to ADDRESS --key-file PATH [--json]

Inputs and options#

  • --endpoint, the provider's send URL; --from and --to, the addresses; --key-file, a regular file only its owner can read, holding the key and nothing else. The declaration is kept in `mail-provider.json` beside Oko's other registers (`OKO_MAIL_PROVIDER` names another file).

Output and state effect#

  • Writes the provider, replacing an earlier one, and prints it (`endpoint`, `from`, `to`, `key file`; the key itself is never printed). An ask delivered on `mail` is then sent with `Authorization: Bearer <key>` and the delivery row says `sent to <to> through <endpoint>: <status> <body>`.
  • The ignored `asks-mail` journey uses an isolated signed-in member and a genuine declared provider, never a loopback substitute. It first checks refusal without a provider, declares one, chooses only mail for that test member, creates and withdraws an ask, and reads the provider's retained message by its returned id to verify the actual recipient and subject. It clears the test member's channel and provider and retains the source revision, binary digest, CLI exit and streams and external result under `.build/asks-mail/<revision>`. Its inputs are the isolated session under this checkout's `.build` and `OKO_TEST_MAIL_ORGANIZATION`, `OKO_TEST_MAIL_DATABASE`, `OKO_TEST_MAIL_ANON_KEY`, `OKO_TEST_MAIL_ENDPOINT`, `OKO_TEST_MAIL_STATUS_ORIGIN`, `OKO_TEST_MAIL_FROM`, `OKO_TEST_MAIL_TO`, `OKO_TEST_MAIL_KEY_FILE`, and `OKO_TEST_SOURCE_REVISION`; a missing dependency refuses qualification.
  • `OKO_TEST_MAIL_SESSION` must name the isolated member's signed-in session file inside this checkout's `.build`; the status origin must support `GET <origin>/<provider message id>` with the same key. The test account must begin with no contact choices. No provider key or operator contact preference is copied into the test.

Refusals and safe exits#

  • `oko contact mail set requires --endpoint <text>`, the same for --from, --to and --key-file; `the mail provider's send endpoint is required` and the same for the sender and destination (exit 2).
  • `the mail provider's key file <path> cannot be read: <error>`, `… is not a regular file`, `… is readable by others; make it owner-only before it is used`, `… is empty` (exit 1): nothing is written on a refusal.
  • At delivery: `no mail provider is declared in <path>; declare one with …` names the command; `the mail provider at <endpoint> refused the message: <status> <body>` and `the mail provider at <endpoint> could not be reached: <error>` are that delivery's failed row, read by `oko asks list` and delivered again by `oko asks deliver`.

CLI reference#