> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.tuco.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to create an API key for iMessage Automation using Tuco AI?

# 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](https://app.tuco.ai/integrations?tab=api-keys). The **API Keys** tab is selected by default.


![](https://storage.crisp.chat/users/helpdesk/website/-/7/e/3/7/7e374bbd96522000/image_1whql7z.png)


### 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**.

![](https://storage.crisp.chat/users/helpdesk/website/-/7/e/3/7/7e374bbd96522000/image_1y97tz0.png)

### 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.

||| This is the only time the full key is shown. After you dismiss the banner or leave the page, only the first few characters are visible. If you lose it, just delete the key and create a new one.

![](https://storage.crisp.chat/users/helpdesk/website/-/7/e/3/7/7e374bbd96522000/image_rb6hvi.png)

## 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:

```bash
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](https://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](https://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](https://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.