Connect your agent
An AI app, a script or your own code works in one workspace, with a key whose permissions and limits the workspace owner chose. Every call goes through the same checks, send ledger and inbox as the console.
Before you start
You need a colding account our team opened, and a workspace you own. Only the workspace owner can connect an agent or make an API key.
Read calls work right away. Calls that send email or reach another server wait until the workspace owner accepts the acceptable use policy in Settings. Until then, those calls answer 403 AUP_REQUIRED.
Any MCP app
Add this MCP address in your AI app and choose Connect:
https://api.colding.app/mcpWhen the app asks, sign in to your colding account, pick the workspace you own, choose the permissions and set any limits. Read (read) is selected to start. The connection creates a key in Agents › API keys with the choices you made.
If your MCP client does not support OAuth sign-in, send stateless Streamable HTTP requests to the same address with Authorization: Bearer cd_your_key on every call.
A script with no browser
When your script runs on a server or in a terminal with no browser callback, ask https://api.colding.app/oauth/device_authorization for a device code with client_id=colding-cli and resource=https://api.colding.app/mcp.
Your script prints a short code. Open https://console.colding.app/auth/device in your browser, sign in, type the code, and pick the workspace, permissions and limits. Approve only a code you just started yourself. Your script polls https://api.colding.app/oauth/token at the stated interval until you approve it.
Your own code
Open Agents › API keys in the console and make a key with only the permissions your code needs. The full cd_ key is shown once. Keep it on your server, never in browser code or a public repository.
Install the TypeScript SDK on Node 20 or newer, or call the REST API at https://api.colding.app/v1 with Authorization: Bearer cd_your_key:
npm install coldingPermissions by job
Give each key only the permissions its job needs. Left is the job, and right are the permission names as the console shows them, with the API grant code for each one:
- Read your inbox
- Read (
read). Reads threads, messages, mailboxes, contacts, campaigns, checks, send status and events without marking anything as read. - Answer replies
- Read and Send outreach (
read,send). Add Operate (operate) when the agent also creates or edits drafts before sending. - Run campaigns
- Read, Operate and Send outreach (
read,operate,send). Prepares contacts and steps, launches campaigns and pauses or stops them. - Check addresses
- Read and Check addresses (
read,validate). Starts, retries or cancels address checks and reads the verdicts. - Send app email
- Send app email (
transactional). Sends receipts, sign-in links and password resets from a mailbox you keep for that, and cancels waiting sends. Add Read (read) to follow them afterwards. - Connect mailboxes and set up domains
- Set up the workspace (
setup). Connects mailboxes with their logins, replaces those logins, confirms a mailbox's address with the code we email to it, adds or removes tracking domains, and sets the postal address. With Read (read) too, it can set up and manage a webhook that no person saved.
In Agents › API keys, or on the OAuth consent screen, the owner can also narrow a key to chosen mailboxes for reading or sending, chosen campaigns, outreach or transactional email only, a daily or total send cap, and an expiration date.
Steps that stay with a person
No API key can sign in with Microsoft or Google, disconnect a mailbox, create or change API keys, manage billing, accept the acceptable use policy, or change or delete a webhook that a person saved in the console. Those steps always need a signed-in person.
When an agent reaches a step that needs a person, a key with Operate (operate) and Read (read) can open a handoff request with handoffs.create and give the owner or admin its console link.
Stop an agent
To stop an agent right away, open the Agents page in the console and press Revoke on its key in Agents › API keys. Every new call with that key is refused at once, and any email from that key that has not started going out is canceled before delivery.
To hold mail without revoking the key, lower the key's send limits in Agents › API keys, pause a mailbox or a campaign, or cancel a waiting send with sends.cancel before it leaves.
What colding doesn't do today
colding does not give your agent an email address of its own on our servers, send your app's email from our servers on any plan for sale, write email itself with a built-in language model, or offer a Python SDK.
For mailboxes you connect, you can already attach files to drafts, replies and app email. Store a file with files.create or files.createUpload, then pass its id in fileIds. Sending through our servers does not support attachments.