Campaign pause tool

The one tool that pauses a campaign’s sending.

This tool pauses a campaign’s sending. It needs the permission campaigns:write, which you grant on the Authorize access page when you connect.

This page is generated from the connector’s tool catalogue. It describes 1 tool. Every tool reads or writes only your own account.

Permissions this page needs

• campaigns:write: Pause a campaign’s sending, and change a campaign’s name, description and goal

The permissions reference lists every permission you can grant.

campaign_pause_sending

Your agent host shows this tool as “Pause campaign sending”.

What this changes: Stop a campaign from sending more mail.

The stored sending state becomes PAUSED, and the delivery guard then defers that campaign’s queued mail and retries it later. It is a hold, not a withdrawal, and its bounds are real: a message already queued by a send-now batch is still dispatched, a drip tick that has already selected this campaign can still queue the rest of that batch, follow-up selection does not read the sending state at all, and nothing already sent can be recalled. There is no tool to resume sending; the student does that in the app.

Permissions: This tool needs campaigns:write, which the Authorize access page describes as “Pause a campaign’s sending, and change a campaign’s name, description and goal”.

Risk: safe_write. This tool changes one of your own settings as soon as the agent calls it. It does not ask you to approve first, because the change affects only your own account and you can set it back yourself.

Input

Property	Type	Required	Bounds
campaignId	string	yes	pattern ^[a-f0-9]{24}$
idempotencyKey	string	yes	16 to 128 characters

Example call

campaign_pause_sending input

{
  "campaignId": "c0ffeec0ffeec0ffee000003",
  "idempotencyKey": "example-idempotency-key-0010"
}

Result

A result is never larger than 4,096 bytes.

This tool’s result takes one of these 4 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

Shape 1, where tag is completed

Top-level fields

[
  "operationId",
  "operationStatus",
  "result",
  "scenario",
  "tag"
]

Shape 2, where tag is accepted

Top-level fields

[
  "operationId",
  "operationStatus",
  "scenario",
  "tag"
]

Shape 3, where status is failed

Top-level fields

[
  "error",
  "operationId",
  "scenario",
  "status"
]

Shape 4, where status is uncertain

Top-level fields

[
  "error",
  "operationId",
  "scenario",
  "status"
]

The result may carry a retry hint

A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.

Code	What it means
PERMIT_BACKPRESSURE	Too much work is already running on this connection. The agent should wait for the stated delay and call the tool again.
PERMIT_CONTENTION	Another call was holding the same slot. The agent should wait for the stated delay and call the tool again.

Errors

A call that does not succeed carries one of these codes.

Code	What it means
ACTION_DENIED	Coffee Chats would not let this connection make the change, so nothing was written. The connection may have been revoked, or it may no longer hold the permission this tool needs.
ACTION_EXPIRED	Coffee Chats did not finish the change inside the short window it allows itself, and stopped rather than write late. Nothing was written. Ask the agent to make the change again.
NOT_APPLIED	Coffee Chats stopped before writing anything. Your data is exactly as it was.
OUTCOME_UNKNOWN	Coffee Chats cannot prove whether the change was written and will not guess. Open your Coffee Chats page and look before you decide what to do. Do not ask the agent to retry with a new key, because that could apply the change twice.
SERVICE_UNAVAILABLE	Coffee Chats could not do the work just now and wrote nothing. Try again later.
VERSION_CONFLICT	Your stored preference changed after the agent read it, so nothing was written. Ask the agent to read it again and make the change from what is there now.