Search all skrzynka documentation

Invocation#

text

skrzynka message send --mailbox <MAILBOX> --to <TO> [--to <TO>] [--cc <CC>] --subject <SUBJECT> --body-file <BODY_FILE> [--idempotency-key <IDEMPOTENCY_KEY>]

Purpose#

Originate one plain-text message from a connected mailbox, carrying its own recipients, cc and subject, with idempotency protection.

Inputs and options#

Input or option	Required	Meaning
`--mailbox <MAILBOX>`	Yes	Mailbox UUID or the mailbox's own address. Address matching is case-insensitive and must name exactly one mailbox.
`--to <TO>`	Yes	Bare recipient address. Repeatable, and each value may itself be a comma-separated list; values are validated and deduplicated in the order given. A display name is refused.
`--cc <CC>`	No	Bare cc address, repeatable and comma-splittable on the same rules.
`--subject <SUBJECT>`	Yes	Must not be empty after trimming.
`--body-file <BODY_FILE>`	Yes	Readable regular UTF-8 file; trimmed body must not be empty. The SMTP server accepts or refuses its size.
`--idempotency-key <IDEMPOTENCY_KEY>`	No	Non-whitespace characters. Omission generates a new UUID for this invocation.

Global options accepted on this path are --organization <ID> (required on every command except serve, version and onboarding; none is assumed), --skarbiec-bin <PATH> (default skarbiec) and --text (print results as path: value lines for people instead of JSON).

Output and state effect#

Resolves the mailbox selector, claims an outbound message row by its idempotency key before anything leaves the process, resolves that mailbox's credential, and sends through its SMTP endpoint. No threading headers are written. Prints the stored row: sent with the local provider_message_id, failed with the SMTP refusal the server itself returned, or uncertain with OUTBOUND_UNCERTAIN when terminal SMTP evidence was lost. Repeating the same key with an identical mailbox, recipients, cc, subject, and body returns the first attempt instead of sending twice; a retry after failed or uncertain requires a new key.

Refusals#

Missing --mailbox, --to, --subject, or --body-file is refused by Clap with exit 2.
NOT_FOUND: mailbox was not found; MAILBOX_SELECTOR_AMBIGUOUS: <SELECTOR> names <COUNT> mailboxes (<ID>, <ID>); select one by id.
OUTBOUND_FILE_INVALID: message body file could not be read, message body file must be a regular file, or message body file must contain valid UTF-8 text.
IDEMPOTENCY_KEY_INVALID: idempotency_key must contain non-whitespace characters only; IDEMPOTENCY_KEY_REUSED: idempotency key already belongs to a different outbound message; IDEMPOTENCY_CONFLICT: outbound message request already exists.
OUTBOUND_SUBJECT_INVALID: subject must not be empty.
OUTBOUND_BODY_INVALID: outbound body must not be empty or message body must not be empty. A body the SMTP server will not carry is its refusal, reported as SMTP_REJECTED with the server's own words.
OUTBOUND_RECIPIENT_INVALID: <ADDRESS> is not a valid email address, at least one recipient address is required, outbound message must name at least one recipient, or outbound recipient is not a valid email address.
OUTBOUND_MESSAGE_INVALID: outbound message could not be encoded as an email message.
Credential/profile refusals include SKARBIEC_ITEM_INVALID, SKARBIEC_UNAVAILABLE, SKARBIEC_TIMEOUT, and MAILBOX_PROFILE_INVALID (mailbox sending address is invalid).
SMTP_TLS_FAILED: SMTP TLS configuration was rejected; SMTP_REJECTED: SMTP explicitly rejected the message: <PROVIDER_REFUSAL>. SMTP_UNCERTAIN is deliberately converted to a returned uncertain row rather than an exit-1 refusal.