Outbound email and CRM changes
A reply to one customer can run on its own. A send to 4,000 contacts or a bulk CRM update waits for a person who can see the list first.
Updated
A sales or marketing agent that writes one good reply is useful. The same agent sending that reply to the wrong segment of 4,000 people is a week of apologies, unsubscribes and spam complaints. The difference is the size of the list, so that is what the rules key on.
The risk
- The wrong list. A filter that matched every contact instead of the trial users who churned.
- The wrong words at scale. A discount the business did not offer, or a placeholder left in the subject line.
- Bulk changes to records. Moving 900 deals to “lost” or overwriting the owner field for a whole region.
- Nothing to undo. A sent email cannot be recalled, and a CRM rarely keeps an easy history of a bulk edit.
One name for one, another for many
Your code, which knows the size of the list, picks the action: one recipient is email.send, more than one is email.send_bulk. The same for crm.update and crm.update_bulk. The model never chooses the name.
The rules
- Always allow email.send, for sales-agentA message to one person runs at once. The exact name does not cover email.send_bulk.
- Always allow crm.update, for sales-agentChanging one record, such as a deal stage after a call, runs at once.
- Always ask about email.send_bulk, for Mia, anyone after 2 hoursEvery send to more than one person goes to the person who owns campaigns.
- Never allow crm.delete*The star needs no dot before it, so this covers crm.delete and crm.delete_bulk. Deleting contacts stays with people.
The same rules as API bodies
# POST /v1/workspaces/{workspace_id}/rules, one call per rule
{
"action": "email.send",
"agent_key_id": "SALES_AGENT_KEY_ID",
"effect": "allow"
}
{
"action": "crm.update",
"agent_key_id": "SALES_AGENT_KEY_ID",
"effect": "allow"
}
{
"action": "email.send_bulk",
"deciders": [
"USER_ID_OF_MIA"
],
"effect": "ask",
"escalate_after_seconds": 7200
}
{
"action": "crm.delete*",
"effect": "deny"
}Owners write rules under Rules in the app, or post these bodies while signed in. Replace the ids in capitals with your own.
Allow by exact name, ask and deny by family. An allow rule for email.* would also cover email.send_bulk; an allow for email.send covers only that.
crm.update_bulk has no rule, so it waits for any member. Give it a routed ask rule like the one for email if one person owns the CRM.
The agent’s side
import { ApprovalClient } from "@variantgate/agent";
const approvals = new ApprovalClient({
agent: "sales-agent",
apiUrl: process.env.VARIANTGATE_API_URL ?? "https://api.variantgate.com",
key: process.env.VARIANTGATE_KEY ?? "",
});
/** Sets the same fields on many CRM records, after a yes. */
export function updateRecords(kind: "contact" | "deal", ids: string[], fields: Record<string, string>) {
const changes = Object.entries(fields).map(([name, value]) => `${name} to "${value}"`);
return approvals.guard(
{
action: ids.length === 1 ? "crm.update" : "crm.update_bulk",
summary: `Set ${changes.join(", ")} on ${ids.length} ${kind}s`,
details: { records: ids.length, kind, fields, "first five": ids.slice(0, 5).join(", ") },
},
async () => {
await crm.batchUpdate(kind, ids, fields);
return `updated ${ids.length} ${kind}s`;
}
);
}from variantgate import VariantGateError, require_approval
def send_campaign(segment, subject: str, html: str) -> str:
"""The bulk-send tool the model calls. Returns what the model should read."""
# Fix the list before asking, and send exactly the list that was approved.
contacts = crm.contacts_in(segment.id, subscribed=True)
emails = [contact.email for contact in contacts]
try:
with require_approval(
"email.send_bulk" if len(emails) > 1 else "email.send",
f"Email {len(emails):,} contacts in '{segment.name}': {subject}",
agent="campaign-agent",
details={
"segment": segment.name,
"recipients": len(emails),
"first five": ", ".join(emails[:5]),
"subject": subject,
"text": plain_text(html)[:1000],
},
ttl_seconds=4 * 60 * 60,
) as approval:
batch = mailer.send_batch(to=emails, subject=subject, html=html)
approval.note = f"batch {batch.id}"
return f"Sent to {len(emails):,} contacts."
except VariantGateError as refused:
return f"Not sent. {refused} Do not send it another way."curl -X POST https://api.variantgate.com/v1/requests \
-H "authorization: Bearer $VARIANTGATE_KEY" \
-H 'content-type: application/json' \
-d '{
"action": "email.send_bulk",
"agent": "campaign-agent",
"details": {
"first five": "li@example.com, sam@example.org, …",
"recipients": 4212,
"segment": "Trial ended, no purchase",
"subject": "Your trial ended. Here is 20% off"
},
"summary": "Email 4,212 contacts in '\''Trial ended, no purchase'\'': Your trial ended. Here is 20% off",
"ttl_seconds": 14400
}'{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "request_approval",
"arguments": {
"action": "email.send_bulk",
"agent": "campaign-agent",
"details": {
"first five": "li@example.com, sam@example.org, …",
"recipients": 4212,
"segment": "Trial ended, no purchase",
"subject": "Your trial ended. Here is 20% off"
},
"summary": "Email 4,212 contacts in 'Trial ended, no purchase': Your trial ended. Here is 20% off",
"ttl_seconds": 14400
}
}
}- The list is fixed before asking, and the code sends exactly that list. Re-running the query after the approval could send to people nobody saw.
- The details show the count, the segment, the first five addresses and the start of the text. Details are kept with the request and shown to the person deciding; the CSV export leaves them out.
- If the person rewords the summary before approving, the
withblock raisesChangedApprovalErrorand nothing is sent: this code cannot send different words than it asked about. - The request stays open for four hours, longer than the two-hour escalation, so it can reach someone else if Mia is away.
What the person approving sees
campaign-agent
email.send_bulk · asked just now
Email 4,212 contacts in 'Trial ended, no purchase': Your trial ended. Here is 20% off
For mia@example.com
- first five
li@example.com, sam@example.org, …
- recipients
4212
- segment
Trial ended, no purchase
- subject
Your trial ended. Here is 20% off
- The count and the segment name come first. A count that looks wrong is the reason to deny.
- Deny with a note such as “Exclude customers who bought in the last 30 days”. The agent reads it, can rebuild the list, and asks again.
- Mia gets it first. After two hours anyone in the workspace may decide, and a notice goes to the Slack channel.
Rolling it out
- Start with no rules. Every reply and every update asks. In a few days you see which ones you never refuse.
- Allow the one-to-one actions by exact name, for each agent’s own key. Approving a reply with “And always” in the inbox writes exactly that rule.
- Route bulk sends to the person who owns campaigns, and add the never rule for deletions.
- Read the denials. Each one is a note on what the agent misjudged; feed them back into its instructions.
For requests to delete a person’s data rather than email them, see data deletion and GDPR erasure. How to sort actions like these into tiers is in risk tiers for agent actions.