How do I create an API key for iMessage?

(Draft for help.tuco.ai — publish via Crisp knowledge base. Suggested category: Integrations / API. Screenshots: drag the images into the Crisp editor at each placeholder.)

You need an API key to send iMessages through the Tuco API — from your CRM, scripts, Zapier/n8n, or anything else that can make an HTTP request. Creating one takes about 30 seconds.

Steps

1. Open the API Keys tab

Go to Integrations in the sidebar of your Tuco workspace, or head straight to app.tuco.ai/integrations?tab=api-keys. The API Keys tab is selected by default.

2. Click "Create API Key"

The orange button in the top-right of the API Keys card.

3. Name your key

In the popup:

• Name (required) — something you'll recognize later, e.g. My iMessage API Key.
• Description (optional) — what the key is used for, e.g. Sending iMessages from my CRM and scripts.
• Expiration Date (optional) — leave it empty and the key never expires.

Click Create.

4. Copy your key — you'll only see it once

A yellow banner appears with your new key (it starts with tuco_). Click the copy button and store it somewhere safe — a password manager is ideal.

Using your key to send an iMessage

Pass the key in the Authorization header on every request:

Authorization: Bearer tuco_your_key_here

For example, sending an iMessage directly:

curl -X POST https://app.tuco.ai/api/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipientPhone": "+15551234567", "message": "Hey! This is an iMessage sent via the Tuco API."}'

The full endpoint reference — sending messages, adding leads to campaigns, checking iMessage availability, fetching replies — lives at docs.tuco.ai, and the API Reference & Rate Limits table is right below the API Keys card on the same page.

Managing your keys

• Deactivate / reactivate — click the Active badge next to a key to toggle it. An inactive key is rejected by the API immediately, and you can switch it back on any time.
• Delete — click the trash icon. This is permanent, and anything still using that key stops working.
• Each key shows its prefix, last-used time, and expiry, so you can tell stale keys from live ones at a glance.

Good to know

• API keys are per workspace — a key created in one workspace can't touch another. Rate limits also apply per workspace, across all keys combined.
• Any workspace member can create a key; the key acts on the workspace, not on your personal account.
• Treat keys like passwords: don't commit them to git, don't paste them in shared docs. If a key leaks, delete it and mint a new one — it only takes a few seconds.

API FAQ

Which Tuco API do I use for each action?

• Send a message (iMessage / SMS / email) — POST /api/messages
• Send with attachments — POST /api/messages with an attachmentUrls array
• Get replies on demand — GET /api/replies
• Get notified of a reply in real time — a webhook (message.reply event)
• Get notified of sent / delivered / failed / SMS-fallback — webhooks (message.sent, message.failed, message.fallback)
• Act on an AI-drafted reply — webhook (message.ai_draft)
• Check if a number is on iMessage — GET /api/check-availability
• Let an AI assistant drive Tuco (Claude, Cursor, Windsurf…) — the MCP server: npx tuco-mcp

How do I receive replies and events?

Two ways. Webhooks (recommended): register an endpoint and Tuco POSTs each event to you in real time — message.reply, message.sent, message.failed, message.fallback, message.ai_draft. Polling: call GET /api/replies?recipientPhone=... or ?leadId=... on a schedule.

Do I need A2P 10DLC to use the API?

No. iMessage runs on Apple's network, not the US carrier SMS system, so there's no A2P 10DLC registration and no per-message carrier surcharge. If a recipient isn't on iMessage, you can fall back to SMS by setting messageType to "sms".

Can I connect an AI agent?

Yes — two ways. Use the MCP server (npx tuco-mcp with your TUCO_API_KEY) for MCP-capable clients like Claude Desktop and Cursor, or register send_imessage as a tool/function on any model and route it to POST /api/messages. There's a full copy-paste build guide at tuco.ai/build-ai-agent.

Where are the full docs and rate limits?

The complete reference — every endpoint, webhook event, and the MCP tool list — is at docs.tuco.ai. Your current rate limits are shown in the API Reference & Rate Limits table right below the API Keys card in the dashboard.

Questions, or want help wiring the API into your stack? Message us right here in the chat — happy to help.

Updated on: 20/08/2026