email warmup

Invocation#

echo-cli email warmup list
echo-cli email warmup add --address <email> --daily-cap <n> --start-cap <n> --increment <n> --start <ISO instant>
echo-cli email warmup plan --identity <identity-id> --daily-cap <n> --start-cap <n> --increment <n> --start <ISO instant>
echo-cli email warmup pause --identity <identity-id>
echo-cli email warmup resume --identity <identity-id>

Inputs and output#

list writes every email sending identity, oldest first: id, channel, from_address, daily_cap, warmup_start_cap, warmup_daily_increment, warmup_started_at (null for no ramp), active, created_at, cap_today (the ramped cap now), sent_today (the emails it sent since day_start: its campaign emails, and the release announcement emails that went out from its from_address, as each announcement delivery records its sender in sent_from) and day_start (the start of the UTC day). The campaign worker holds an identity to its cap with the same count, so announcements sent from a warming address spend its cap too. add, plan, pause and resume write the identity they made or changed.

State effect#

Every verb calls Echo Web's authenticated /api/crm/identities with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the /campaigns/identities screen and the Sending identities and warm-up section of Echo Desktop's Contact frequency screen call the same operations, and echo-mcp reads them as echo_sending_identities. Identities are rows of crm_sending_identities. An identity's cap on a day is warmup_start_cap on the day its ramp starts (and before it), growing by warmup_daily_increment each whole day after, never above daily_cap; with no start it is daily_cap. A start cap equal to the daily cap is no ramp. The campaign worker sends each campaign email from the first active identity, oldest first, whose emails since the start of the UTC day — campaign emails and announcement emails sent from its address — are under its cap, and records which identity sent it; when every active identity is at its cap, the recipient is not sent this tick and keeps its status, the deferral naming each identity's count and cap: "every sending identity is at its cap today (since <instant>): <address> sent <n> of its <cap> today; …". With no active identity, campaign email goes out from CRM_OUTREACH_FROM. A paused identity sends nothing until resumed.

Refusals#

• A wrong invocation is refused before anything is sent: "email warmup takes <every warmup usage>; got <word>", "email warmup <verb> does not take <flag>; it takes …", "<flag> needs a value", "email warmup <verb> needs <flag>" and "--daily-cap must be a whole number of emails; got <value>" (and --start-cap, --increment).
• Echo Web answers a bad request with "address must be one email address, a local part and a domain around one @; got <value>", "daily_cap must be a whole number of at least 1: the most campaign emails the identity sends in a UTC day once warmed up; got <value>", "warmup_start_cap must be a whole number of at least 1: the cap on the day the ramp starts; got <value>", "warmup_daily_increment must be a whole number of at least 0: how much the cap grows each day after the start; got <value>", "warmup_start_cap <n> is above daily_cap <n>; the ramp ends at the daily cap", "warmup_started_at must be an ISO instant or null; got <value>", "identity_id is required: …" or "active must be true to resume the identity or false to pause it; got <value>"; not found with "no sending identity has id <id>; echo-cli email warmup list shows them"; and a conflict with "<address> is already the sending identity <id>; echo-cli email warmup plan changes its plan" or "sending identity <address> (<id>) is already active|paused". The command prints Echo Web's sentence and exits 1.