Deskhand

它列出的 30 个工具

“只读”和“会改数据”是服务方自己标的。带下划线的参数是必填的。

1. add_note

   Add a note

   Attach a note to a contact (by id or email) or to a deal. Requires the write_crm scope.

   body contact_id contact_email deal_id idempotency_key

2. add_suppression

   Add to the suppression list

   Never email this address or domain again, in any campaign. Open enrollments of matching contacts stop. Removing an entry needs the operator. Requires the manage_campaigns scope.

   value reason idempotency_key

3. campaign_report只读

   Campaign report

   Counts per campaign, per step and per variant: enrolled, active, completed, stopped (by reason), sent, sent_dry (dry-run records, nothing delivered), skipped (by reason), replied, bounced, unsubscribed, meetings, deals_created. Rates say which count they divide by.

   campaign_id

4. create_campaign

   Create a campaign

   Create a campaign: an ordered sequence of email, wait and task steps run per contact, with follow-ups, stop rules (reply, bounce, unsubscribe and deal stage change stop a contact's sequence), a send window, caps and A/B variants. Pass steps inline, and optionally `enroll` to select contacts in the same call. It starts as a draft; call simulate_campaign, then launch_campaign. Delivery is a dry run (nothing leaves the system) until the operator switches sending on. Requires the manage_campaigns scope.

   name description strategy steps enroll identity_id timezone_mode timezone window send_days skip_dates daily_cap stop_on track_opens footer opt_out_line idempotency_key

5. create_deal

   Create a deal

   Open a deal, optionally linked to a contact (by id or email) and a company. Stages: lead, contacted, qualified, proposal, won, lost. The deal takes its contact's company unless company_id is given. Unknown arguments are rejected with unknown_field. Requires the write_crm scope.

   title contact_id contact_email company_id stage value_cents currency source fields idempotency_key

6. create_task

   Create a task

   Create a follow-up task or reminder with an optional due date, on a contact or a deal. Requires the manage_tasks scope.

   title due_at contact_id deal_id idempotency_key

7. draft_email

   Draft an email

   Draft one email to a contact. Drafts are auto-approved by default (the operator can switch approval on for the workspace or for you; then the draft waits in their Approvals inbox). Approved mail that cannot be sent to the recipient yet waits in the operator's To send list and the response says so. Refuses with contact_suppressed when the contact replied, unsubscribed or bounced. One recipient per message, plain text, no attachments. Accepts only contact_id (or to), subject, body and an optional note (your one-line reason for writing it, up to 500 characters, shown to the operator on the approval card): any other argument is rejected with unknown_field. The response carries warnings (codes: open_draft_exists when another unsent draft to the same contact exists, emailed_N_days_ago when mail went out in the last 3 days, contact_status_<status>) and prior_emails; check them before drafting a second message to the same person. Requires the draft_email scope.

   contact_id to subject body note idempotency_key

8. enroll_contacts

   Enroll contacts in a campaign

   Enroll contacts by ids, tag, source/list, status, text or custom fields. Suppressed, replied, unsubscribed, bounced, address-less and blocked-domain contacts are skipped with a reason, and a contact in another running campaign is skipped (or moved with on_conflict=move). dry_run=true returns who would be enrolled and who skipped. Requires the manage_campaigns scope.

   campaign_id contact_ids tag source list status q fields dry_run on_conflict claim_check evidence_url per_contact idempotency_key

9. get_campaign只读

   Read a campaign

   One campaign with its steps, status, delivery mode (dry run or live) and counters.

   campaign_id

10. get_outbox

    Read the signed messages to send

    For a campaign that sends through your own sender (relay identity): the operator-approved messages you may send now, each with its exact text, recipient, step and evidence link, plus batch_id and batch_hash. Send the text byte for byte, then call report_send for every message. 409 batch_not_approved until the operator signs the batch; 409 batch_changed if anything changed after sign-off. Requires the manage_campaigns scope.

    campaign_id limit

11. get_policy只读

    Read the sending policy

    What the operator allows this agent: the workspace approval setting and, in plain words, what happens to your CRM writes and email drafts (apply or auto-approve at once, or wait for approval), this agent's mode (direct or propose), daily send caps and how many were used today, blocked domains, and the contact statuses that are never mailed. Read it before planning a batch of drafts.

12. get_thread只读

    Read a contact's thread

    Sent mail and replies for one contact in time order. Requires the read_crm scope.

    thread_id contact_id email

13. launch_campaign

    Launch a campaign

    Start a draft campaign. Refused with launch_blockers (postal address, sender name, an email step, enrolled contacts, a verified identity) until they are fixed. With approval on, it returns 202 and waits for the operator to approve the launch once. Requires the manage_campaigns scope.

    campaign_id idempotency_key

14. list_campaigns只读

    List campaigns

    Campaigns in this workspace with status, delivery mode and enrolled/sent/replied counters. Archived ones are hidden unless status=archived.

    status

15. list_due_tasks只读

    List tasks that are due

    What is due now: overdue and due-today tasks first, then the next 7 days. Tasks on contacts who replied, unsubscribed or bounced are flagged follow_up_blocked: do not chase those. Requires manage_tasks or read_crm.

16. list_email_status只读

    Check email drafts and sends

    Status of this agent's emails: pending_approval (only when approval is on), approved (with a note when it waits in the manual To send hand-off), rejected (with reject_reason to learn from), sent, failed, cancelled. Each email carries warnings (open_draft_exists, emailed_N_days_ago) and prior_emails. Filter by status (comma separated), run_id or contact_id.

    status run_id contact_id limit cursor

17. list_replies只读

    List replies

    Replies captured from contacts, newest first. Requires the read_crm scope.

    since contact_id limit cursor

18. list_sending_identities只读

    List sending identities

    The identities a campaign can send through: the built-in dry_run identity and any the operator connected (their keys are never shown), with their delivery state.

19. list_suppressions只读

    List the suppression list

    Addresses and domains that are never emailed.

    q limit cursor

20. mark_replied

    Mark a contact as replied

    Record that a contact replied (optionally with the reply text). Sets the contact to replied, cancels their pending drafts and open follow-up tasks, and stops further drafts to them. Requires the write_crm scope.

    contact_id email text subject idempotency_key

21. move_deal

    Move a deal to a stage

    Set a deal's stage (lead, contacted, qualified, proposal, won, lost). Requires the write_crm scope.

    deal_id stage idempotency_key

22. pause_campaign

    Pause a campaign

    Freeze a running campaign. Nothing is lost: resuming shifts every pending step by the length of the pause. Requires the manage_campaigns scope.

    campaign_id idempotency_key

23. report_send

    Report what happened to a message

    Report one outbox message: sent (final: the person moves to the next step; reporting sent twice is fine, a different second report is 409 already_reported), refused_cap, refused_unsigned or failed_transient (the message stays in To send and gives its cap unit back), refused_suppressed (the person is suppressed and leaves the campaign). A later bounce is not a report: use add_suppression with reason bounced. Requires the manage_campaigns scope.

    campaign_id email_id outcome provider_id reason idempotency_key

24. resume_campaign

    Resume a campaign

    Resume a paused campaign. Requires the manage_campaigns scope.

    campaign_id idempotency_key

25. search_contacts只读

    Search contacts

    Find contacts by text (name, email, title), status, source, company or a custom field. Returns up to `limit` contacts and a next_cursor. Requires the read_crm scope.

    q status source company_id fields limit cursor

26. simulate_campaign只读

    Simulate what goes out

    What would go out over the next N days: per contact and step, the send time (UTC and local), the fully rendered subject and body, and the status (will_send, skipped_missing_variable, skipped_condition, blocked_by_cap, task_created), plus problems and launch_blockers. Nothing is written or sent. It uses the same planner as the real scheduler, so this is what the scheduler will do.

    campaign_id as_of horizon_days contacts

27. stop_enrollment

    Stop one contact's sequence

    Stop a single enrollment (reason manual). Requires the manage_campaigns scope.

    campaign_id enrollment_id idempotency_key

28. update_campaign

    Edit a campaign

    Change a campaign's settings and/or replace its ordered steps. Editing the steps of a running campaign needs the operator's approval when approval is on. Requires the manage_campaigns scope.

    campaign_id name description strategy identity_id timezone_mode timezone window send_days skip_dates daily_cap stop_on track_opens footer opt_out_line steps idempotency_key

29. update_contact

    Update a contact

    Change fields of an existing contact, found by id or email. Custom `fields` are merged with the existing ones. Requires the write_crm scope.

    id email name title source status company_id timezone fields tags idempotency_key

30. upsert_contact

    Create or update a contact

    Create a contact, or update the one that already has this email (matched case-insensitively). Custom `fields` and `tags` are merged into what is stored. A company is created or reused from company_domain or company_name. Requires the write_crm scope.

    email name title source timezone status company_name company_domain fields tags idempotency_key