Agent agreements

​

Goal

​

Prerequisites

• An agent inbox. See Agent inboxes. Sending from an inbox must be on: its send mode cannot be off.
• To change an inbox’s limits: you must be the owner of the workspace, signed in to the dashboard.
• To work agreements from code: a StackShift API key with Mail access. To work them from an agent: an agent connected over MCP, or Stackie working the inbox.

​

Workflow

​

What an agreement is

• Ask for a quote: say what you want, how much and by when.
• Give a quote: say what you will supply, for how much in total, delivered by when, and how long the offer stays open. A new quote can replace an earlier one, which is how counter-offers work.
• Offer times: give one to five slots for a meeting or a delivery, with a time zone. The other side picks one.
• Accept: say yes to an offer. The offer ends as agreed.
• Decline: say no to an offer or a request, with a reason if you like: price, timing, not available or other.
• Cancel: take back an offer that is still open. Cancelling a deal that was already agreed is recorded, but it never undoes anything outside StackShift.

​

What the other side receives

​

Set limits for an agent inbox

• What this agent may do on its own: ask for quotes, give quotes, offer times, accept quotes, accept times, decline, and cancel its own offers.
• Money, one row for Naira and one for USD: the most it may agree to in one deal and in one day, counting everything agreed that day in that currency. Buying (accepting a quote) and selling (giving a quote) have separate amounts.
• Who it may deal with on its own: anyone who writes to it first, only the domains or addresses on a list, or only other StackShift workspaces whose records can be checked.
• How long its offers stay open: the longest, from 1 hour to 30 days. The default is 3 days.
• Times it may offer or accept: the weekdays, the hours, the time zone, the earliest and the latest day ahead, and the longest slot.
• Stop all agreements for this inbox: one switch that turns the limits off. It cancels nothing already open. Your agent’s kill switches stop all agreement messages at once as well.
• Any currency other than Naira and USD always waits for you. At the Ask me every time level, the agent asks every time, whatever the limits say.

​

Inside the limits and outside them

• It is over your limit for one deal, or over today’s limit.
• The address isn’t on your list, or we couldn’t check who it is.
• The time is outside the hours you allow, or the offer stays open longer than you allow.
• Limits are off, the action isn’t ticked, or this agent asks every time.
• The terms came from their message. See the next section.
• Approve for the agent, decline, or change the limits from the card. Approvals happen in the dashboard, which works on a phone. We never approve agreements from a link in an email, because agreements reach people.
• Cancelling a deal that was already agreed, and counting a person’s reply, always wait for you.

​

When an offer used text from the other side

​

Counting a person’s reply

​

The agreement record

• From the record page you can download the record as a .json file, copy a link to the public check page, and see the result, for example Checks out: signed by Mills & Co (StackShift workspace) and Ada’s Bakes (StackShift workspace) on 3 Nov 2026 14:02 WAT.
• From anywhere, open stackshift.cloud/check, paste or drop a record, and see whether it checks out, who signed it, the terms and whether either key was revoked. No sign-in is needed.
• There are four results: checks out with two signatures, checks out with one signature, their reply recorded by a named workspace, and does not check out, with the reason.

​

Caps, new workspaces and billing

• Each agent inbox can send 30 agreement messages an hour and 200 a day, and 10 an hour to one counterparty. Repeated flooding can switch an inbox’s limits off for you.
• The inbox’s send mode still applies. With replies, an agent can only start a deal with an address that wrote first. With off, there are no agreement messages. Starting deals with strangers needs any.
• New workspaces, in their first week or until the first payment: limits can be saved but every agreement message waits for you, at most 20 agreement messages go out a day, and the any send mode is not available on the StackShift domain.
• Agreement emails count as ordinary agent inbox sends against your Mail allowance. There is no extra charge for agreements. See Agent inboxes for the plan allowances.
• Release 1 has no payment fields. Agreements work on agent inboxes only, and limits cover Naira and USD only.

​

REST API

• GET /mail/agreements: list threads. Query inboxId, state, counterparty, cursor and limit (up to 200). Returns threads, nextCursor and counts of open, waiting_for_you, agreed and ended.
• GET /mail/agreements/{threadId}: one thread with thread, messages, record, replies and changeCursor. GET /mail/agreements/{threadId}/record downloads the record as a file.
• GET /mail/agreements/{threadId}/wait?after={changeCursor}&timeout=50: holds until the next message or change, up to 50 seconds. It returns the same body as the thread, or timedOut with a changeCursor.
• POST /mail/agent-inboxes/{inboxId}/agreements: ask for a quote, give a quote or offer times. Send type (ask_quote, quote or propose_times), and to for a new thread or threadId for an existing one. Quotes carry items and total ({ amount, currency }, with the amount in kobo or cents as a string) and deliveryBy. Times carry slots, purpose and location. Add inReplyTo or replaces, openForSeconds and note.
• POST /mail/agreements/{threadId}/respond: accept or decline by id. Send offerId and decision, and slot for times or reason for a decline. The terms come from the stored offer, never from the request.
• POST /mail/agreements/{threadId}/cancel: cancel an offer with offerId, or an agreement without it. POST /mail/agreements/{threadId}/count-reply with offerId and replyMessageId.
• GET /mail/agent-inboxes/{inboxId}/agreement-limits: the limits, usedToday, sentLastHour and sentToday. PUT to the same address saves them, with expectedVersion, for the owner only. A conflict returns 409.
• GET /mail/agreements/keys, POST /mail/agreements/keys/rotate and POST /mail/agreements/keys/{kid}/revoke: the workspace signing key, owner only.
• POST /api/v1/public/agreements/check: check a record from anywhere, with no key. Send the record, or { “jws”: ”…” } for a signed message. Rate limited.

curl https://api.stackshift.cloud/api/v1/mail/agent-inboxes/$INBOX_ID/agreements \
  -H "Authorization: Bearer $STACKSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: flour-ask-1" \
  -d '{"type":"ask_quote","to":"orders@adasbakes.com","items":[{"description":"Flour, type 55","quantity":"200","unit":"kg"}],"wantedBy":"2026-11-07"}'

{
  "threadId": "5f1d8c1e-2b8f-4a7e-8f0a-6c1d2e3f4a5b",
  "messageId": "0b6b1b52-6a0f-4c55-9a43-2f6f1d6f8e01",
  "state": "sent"
}

curl https://api.stackshift.cloud/api/v1/mail/agreements/$THREAD_ID/respond \
  -H "Authorization: Bearer $STACKSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: flour-accept-1" \
  -d '{"offerId":"0b6b1b52-6a0f-4c55-9a43-2f6f1d6f8e02","decision":"accept"}'

​

SDKs

import { StackShift } from '@stackshift-cloud/sdk'

const stackshift = new StackShift({ apiKey: process.env.STACKSHIFT_API_KEY })
const inboxId = process.env.INBOX_ID

const sent = await stackshift.mail.agreements.propose(
  inboxId,
  {
    type: 'ask_quote',
    to: 'orders@adasbakes.com',
    items: [{ description: 'Flour, type 55', quantity: '200', unit: 'kg' }],
    wantedBy: '2026-11-07',
  },
  { idempotencyKey: 'flour-ask-1' },
)

const thread = await stackshift.mail.agreements.get(sent.threadId)
const change = await stackshift.mail.agreements.waitForChange(sent.threadId, { after: thread.changeCursor })

const offer = change.thread.openOffer
if (offer && change.thread.amount?.currency === 'NGN') {
  await stackshift.mail.agreements.accept(sent.threadId, { offerId: offer.id }, { idempotencyKey: 'flour-accept-1' })
}

import os
from stackshift import StackShift

stackshift = StackShift(api_key=os.environ["STACKSHIFT_API_KEY"])
inbox_id = os.environ["INBOX_ID"]

sent = stackshift.mail.agreements.propose(
    inbox_id,
    type="ask_quote",
    to="orders@adasbakes.com",
    items=[{"description": "Flour, type 55", "quantity": "200", "unit": "kg"}],
    wanted_by="2026-11-07",
    idempotency_key="flour-ask-1",
)

thread = stackshift.mail.agreements.get(sent["threadId"])
change = stackshift.mail.agreements.wait_for_change(sent["threadId"], after=thread["changeCursor"])

offer = change["thread"]["openOffer"]
amount = change["thread"]["amount"]
if offer and amount and amount["currency"] == "NGN":
    stackshift.mail.agreements.accept(sent["threadId"], offer["id"], idempotency_key="flour-accept-1")

client, err := stackshift.New(stackshift.Options{})
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()
inboxID := os.Getenv("INBOX_ID")

sent, err := client.Mail.Agreements.Propose(ctx, inboxID, stackshift.ProposeAgreementInput{
	Type:     "ask_quote",
	To:       "orders@adasbakes.com",
	Items:    []stackshift.AgreementItem{{Description: "Flour, type 55", Quantity: "200", Unit: "kg"}},
	WantedBy: "2026-11-07",
}, stackshift.AgreementSendOptions{IdempotencyKey: "flour-ask-1"})
if err != nil {
	log.Fatal(err)
}

thread, err := client.Mail.Agreements.Get(ctx, sent.ThreadID)
if err != nil {
	log.Fatal(err)
}
change, err := client.Mail.Agreements.WaitForChange(ctx, sent.ThreadID, thread.ChangeCursor)
if err != nil {
	log.Fatal(err)
}

if offer := change.Thread.OpenOffer; offer != nil && change.Thread.Amount != nil && change.Thread.Amount.Currency == "NGN" {
	_, err = client.Mail.Agreements.Accept(ctx, sent.ThreadID, offer.ID, nil, stackshift.AgreementSendOptions{IdempotencyKey: "flour-accept-1"})
}

const record = await stackshift.mail.agreements.record(threadId)
const check = await stackshift.mail.agreements.check(record)
console.log(check.result, check.summary)

const limits = await stackshift.mail.agreements.limits.get(inboxId)
console.log(limits.enabled, limits.usedToday.NGN)

record = stackshift.mail.agreements.record(thread_id)
check = stackshift.mail.agreements.check(record)
print(check["result"], check["summary"])

limits = stackshift.mail.agreements.limits.get(inbox_id)
print(limits["enabled"], limits["usedToday"].get("NGN"))

raw, err := client.Mail.Agreements.Record(ctx, threadID)
if err != nil {
	log.Fatal(err)
}
check, err := client.Mail.Agreements.Check(ctx, raw)
if err != nil {
	log.Fatal(err)
}
fmt.Println(check.Result, check.Summary)

limits, err := client.Mail.Agreements.GetLimits(ctx, inboxID)

​

CLI

• stackshift agreements list, show, record, wait, propose, accept, decline, cancel, count-reply and check. Run any of them with —help for its options.
• stackshift agreements accept AGREEMENT —offer OFFER and stackshift agreements decline AGREEMENT —offer OFFER answer an offer by its id. Accept takes —slot for offered times, decline takes —reason, and both take —note. Commands that send ask you to confirm; add —yes in scripts.
• stackshift agreements record AGREEMENT —download FILE saves the record, and stackshift agreements check FILE checks it without signing in.
• stackshift agreements limits show prints an inbox’s limits and today’s use. stackshift agreements limits set opens the dashboard, because only the owner changes limits.

​

Connected agents (MCP)

​

Events and webhooks

• agreement.offer_received: an offer or a request arrived and passed its checks.
• agreement.waiting_for_you: a message waits for your approval, or a person’s reply waits to be counted.
• agreement.agreed: an offer was accepted and the record was made.
• agreement.declined and agreement.cancelled: the offer was declined or cancelled.
• agreement.expired: the offer stayed open until its time ran out.
• agreement.check_failed: a message had an agreement part that we could not check. It stays a normal email.

{
  "threadId": "5f1d8c1e-2b8f-4a7e-8f0a-6c1d2e3f4a5b",
  "inboxId": "9d2b6e0a-3c41-4f6e-9a1d-7b5c2e8f0a13",
  "messageId": "0b6b1b52-6a0f-4c55-9a43-2f6f1d6f8e02",
  "state": "agreed"
}

​

For developers: the open format

​

Expected result

​

Common failures

​

Related guides