Skip to content

Sending

Customer.lite lets an AI assistant build and run your email, but not decide on its own to send it. Three things stand between a workflow and a customer’s inbox: a verified sender, a preview the caller confirms, and a person who approves. Then every single send is checked again just before it goes out.

Every from address of a workflow must be at a verified sending domain of the workspace. Activating a workflow whose from domain is not verified answers sender_not_verified, and a send whose domain stops being verified is skipped with the same reason.

Sending domains are set up by whoever operates your installation, through operator endpoints that are not part of the API (Setting up Amazon SES shows them for a self-hosted installation). Adding and verifying your own domains from the dashboard or the API is planned.

A domain is verified once the email provider has checked its DNS records: the DKIM records the provider gives you and, if you use one, a custom MAIL FROM subdomain, which aligns SPF with your domain. Publish a DMARC record for the domain as well; large mailbox providers expect one from anyone who sends in bulk.

workflows.activate is the action that can start sending. It never sends on the first call:

  1. Preview. Called without confirmation, it changes nothing and answers:

    {
    "status": "confirmation_required",
    "preview": {
    "action": "workflows.activate",
    "workflow": { "id": "welcome", "name": "Welcome", "version": 2, "liveVersion": 1 },
    "recipients": { "exact": false, "triggerEvent": "user.signed_up", "customersWithTriggerEventLast30Days": 120 },
    "sends": [{ "stepId": "welcome", "from": "hello@yourdomain.example", "subject": "Welcome aboard", "body": "…" }],
    "approvalRequired": true,
    "warnings": []
    },
    "confirmation": { "token": "cl_conf_…", "expiresAt": 1767225600000 }
    }

    An assistant shows this preview to you and waits for your answer.

  2. Confirm. Only if you agree, it calls again with the same input and "confirmation": "<token>". The answer is { "status": "done", "result": … }.

The token is bound to the caller, the action, and the exact input, works once, and expires after 15 minutes by default. A token that does not match answers confirmation_invalid (409) with a fresh preview and token. A retry of a confirmed call returns the first result, so a network retry never commits twice. Activating a version with no send_email step starts no sends, and runs at once with done.

The server enforces this for every client, so it holds even for a client that ignores MCP tool hints.

A preview proves that the caller saw what would be sent, not that a person decided: whoever holds the key can confirm. So a workflow version that sends email also needs a human approval, through a channel the caller never sees.

  • The confirmed workflows.activate call does not make the version live. Its result holds a pending sendApproval, and each approver of the workspace gets an email with their own approval link. The link is not in any API or MCP response, unless a self-hosted installation sets SEND_APPROVAL_DELIVERY=response (Self-hosting).
  • The approver opens the link, sees the version, and approves or declines it. Approving makes that version live; declining leaves the workflow as it was.
  • An approval binds one exact version. It expires after 24 hours, and it is superseded when a newer version is saved. Calling workflows.activate again for the same version mails new links and invalidates the earlier ones.
  • sendApprovals.get shows its status: pending, approved, declined, cancelled, expired, or superseded.

A workspace with no approvers answers no_approvers. On a self-hosted installation the approvers are the addresses in ADMIN_EMAILS; otherwise the installation’s operator sets them. If a link could not be mailed to every approver, the call answers approval_delivery_failed; previewing and confirming again mails new links to those who did not get one.

Approval is required for every sending workflow today, during early access. Making it optional per workspace, with pause and rollback, is planned.

Pausing a workspace’s sending automatically when its bounce or complaint rate passes a threshold is planned. Until then, watch metrics.get, and see the next section for what Customer.lite already does with each bounce and complaint.

  • One-click unsubscribe. Every workflow email carries List-Unsubscribe and List-Unsubscribe-Post headers with a link of its own, so mail clients can offer an unsubscribe button that works in one click. A person who opens the link in a browser gets a page with an Unsubscribe button.
  • From your application. customers.unsubscribe unsubscribes a customer, for example from your own settings page. Sends already waiting are rechecked and skipped.
  • Suppression. A complaint, or a hard bounce, adds the address to the project’s suppression list. Customer.lite does not send to it again.

Just before each send, Customer.lite checks again that the customer still exists, has an address, has not unsubscribed, is not suppressed, that the run has not been stopped, and that the from domain is still verified. A send that fails a check is skipped, with the reason, and the step log records it.

Each send_email step produces one message per run. messages.get returns its state, with a reason where one explains it, and its deliveryStatus.

State Meaning
queued Waiting to be sent, or to be retried after a temporary provider error.
waiting Held until a plan limit allows it. Plan limits are planned, so no message waits here yet.
sending Being handed to the email provider.
accepted The provider accepted it. This is when it counts as a billable email.
unknown The provider’s answer was lost (a timeout, for example). It is never resent blindly: an unknown outcome is resolved from the provider’s delivery events, or becomes failed after 72 hours.
failed The provider refused it, retries ran out, or its outcome stayed unknown.
skipped Not sent, with the reason: customer_missing, no_address, unsubscribed, suppressed, workflow_stopped, or sender_not_verified.

deliveryStatus is what the provider reported afterwards: delayed, soft_bounced, delivered, content_rejected, bounced, or complained. metrics.get counts the project’s billable emails, deliveries, bounces, and complaints.