# Inkbox: iMessage, SMS, email & calls

Text, email, or call your agent. It does the work and replies the same way.

Canonical page: https://themachine.myapps.ai/docs/connect/inkbox

The Inkbox channel lets you reach your Machine agent the way you'd reach a
person: by iMessage, SMS, email, or phone. Each text or email from an allowed
sender starts a [session](/docs/work/sessions) in your project, or continues
the one for that conversation. Calls are answered live by Inkbox Voice AI;
when you hang up, the transcript and any to-dos go to your agent, which does
the work and follows up.

The channel runs on your own [Inkbox](https://inkbox.ai) account. Inkbox owns
the phone line and the mailbox; Machine owns the agent. Inkbox is on for every
project: there's no switch to turn on, and nothing runs until you connect your
own Inkbox key.

Using Machine Desktop? See the step-by-step [Inkbox guide for Machine
Desktop](/docs/desktop/inkbox), with screenshots. The desktop app shows an
Inkbox row in each bot's **Channels** settings, can disconnect it, and opens
this page's setup on the web for you.

## What you need

- A Machine project you can edit connectors in.
- An Inkbox account with an **agent** (Inkbox calls it an agent identity).
  Every agent comes with a handle, such as `@machine`, and a mailbox, such as
  `machine@inkboxmail.com`.
- An Inkbox **API key**. An admin key works, and so does a key scoped to
  that one agent.
- Who may reach the agent: phone numbers for iMessage, SMS, and calls, email
  addresses or domains for email.

**No phone number needed.** iMessage and voice calls work through Inkbox's
shared iMessage line, and email through the agent's mailbox, all on Inkbox's
free plan. A phone number of the
agent's own (Inkbox Console → **Phone**) is optional. It adds SMS from any
phone (Android too), calls to and from any phone, and one number to hand out.

## Set it up

### Get your Inkbox API key

In the [Inkbox Console](https://inkbox.ai/console), create an agent if you
don't have one. Then open **API Keys** and create a key. Copy it. Inkbox shows
it only once.

Never paste the key into a chat with the agent. It belongs only in the
Settings form in the next step.

### Connect Inkbox

Open the project's **Settings → Channels**. Inkbox has its own card there,
marked **Your own account**. Click **Connect Inkbox**, paste the API key, then
fill in one or both lists:

- **Phone**: numbers allowed to iMessage, text, or call the agent, one per line
with the country code (`+14155550100`).
- **Email**: addresses allowed to email the agent (`dana@acme.com`), or a whole
domain written `@acme.com`.

Leave a list empty to keep that one off, but fill in at least one. If the key
can see more than one Inkbox agent, Machine asks _Which Inkbox agent should
Machine be?_ Pick one and click **Connect Inkbox** again.

When you connect, Machine:

- turns iMessage on for that Inkbox agent (if you listed numbers),
- points the agent's incoming iMessages, SMS, emails, and finished calls at
your project,
- creates the agent's project note in Inkbox (see [Memory](#memory)), and
- stores the key on the server. It never enters the agent's sandbox.

### Connect your phone (iMessage)

Click **Manage** on the Inkbox card. Under **Connect your phone to text the
agent** (one time per phone), it shows exactly what to send, for example
_text `connect @machine` to +1 (650) 484-9720_. Send that text once from each
allowed phone. **Copy** copies the text, **Open in Messages** drafts it for
you, or scan the QR code with your phone camera. Inkbox replies with the
agent's contact card. Save it.

Below the instructions, each number on your list shows **Connected** or
**Not connected yet**, and updates while **Manage** is open.

Email needs no setup step: just write to the agent's address, also shown under
**Manage**.

SMS needs a phone number on the agent, but no connect text: text that number
from any phone. In the US, text **START** to it once first, so the agent is
allowed to text you back.

### Text or email your agent

Ask for anything you'd ask in a session: _"Check if the site is up"_,
_"Summarize yesterday's sessions"_, _"Draft a reply to Dana's question"_.

For anything that takes a while, the agent sends a quick _"On it"_ first, then
the result. Replies in the same text conversation or email thread continue the
same session, so follow-ups keep their context.

To start fresh in the same text conversation, text **`/new`**. That starts a
new session; the old one stays in your session list. You can put the request
right after it: _`/new check if the site is up`_. For email, start a new
thread (a new subject) instead.

## What Manage shows

Once Inkbox is connected, the card shows **Connected** with the agent's
handle and what's live, for example _@machine · iMessage, calls + email_.
**Manage** opens everything else:

- **How to reach the agent.** Without a number of its own, the top says
  _@machine is ready to reach_, **No phone number needed**, and lists iMessage,
  voice calls, and email as **Ready** or **Off**. **SMS from any phone** has an
  **Add a number** link to the Inkbox Console; it's optional. Once the agent
  has a number, the top shows it large instead, with **Text** and **Call**
  buttons and a QR code people can scan to text it. Add a number in the Inkbox
  Console and Machine picks it up by itself.
- **Agent and model**: see [Agent and model](#agent-and-model).
- **Contact photo**: the picture people see when the agent texts or calls
  them, and on its contact card. The first time you open **Manage**, an agent
  with no photo gets a Machine mascot. **Shuffle** draws a new one, **Use this
  photo** saves it to Inkbox, and **Remove photo** clears it.
- **Connect your phone to text the agent**, **Email the agent**, and **Call
  the agent**: the steps and addresses from the setup above.
- The **Phone** and **Email** lists. Edit them and click **Save**.

## Calls

Calls work differently from texts and email, because a phone call is live:

- **You call the agent.** Inkbox Voice AI answers on the agent's Inkbox phone
  number or iMessage line and talks with you. It writes down anything that
  needs doing as an action item. When you hang up, the transcript and the
  action items go to your agent in a new session. It does the work and follows
  up by text or email.
- **The agent calls someone.** Ask in any session, for example _"call Blue Harbor
  Dental and book me a cleaning next week, mornings"_. Voice AI places the call
  and handles the conversation. When it ends, the transcript and outcome come
  back into the same session, and the agent tells you how it went. To call
  any phone, such as a business, the agent needs a number of its own. Without
  one, it can call only people who connected to it over iMessage.

Calls from numbers that aren't on your phone list still get answered by Inkbox
(that's set in the Inkbox Console), but nothing reaches your agent. Voice AI's
voice and standing instructions are set in the Inkbox Console, or ask the
agent: _"make the phone voice warmer and tell callers we're closed Sundays"_.

## Agent and model

Click **Manage** on the Inkbox card to choose which agent answers texts, email,
and calls, and which model it runs. Left on **Default** and **Project
default**, it follows the project's default agent and model, and the picker
shows which model that is. New conversations use your choice; a conversation already in progress
keeps the session it started with. Reconnecting Inkbox keeps your choice.

Once Inkbox is connected, every agent in the project can use it, like any
connected [connector](/docs/connect/connectors#grant-an-agent-access). You
don't need to add `kortix_inkbox` anywhere. Disconnecting takes that access
away again.

## Memory

The agent keeps its memory in Inkbox **notes**, so it remembers people across
sessions and across channels:

- **One note per person**, titled `@machine · +14155550100` (their number or
  email). After each conversation the agent writes down who they are, what they
  asked, what it did, and what's still open. Text today and call tomorrow, and
  the agent picks up where it left off.
- **One project note**, titled `@machine · Machine project`. Machine creates it
  when you connect; the agent adds lasting facts about the project.

You can read and edit every note in the Inkbox Console. The agent never writes
secrets or passwords into a note.

## What the agent can do in Inkbox

Beyond replying, the agent can use the rest of Inkbox when you ask:

- **iMessage**: tapbacks, inline replies, message effects, group chats (with a
  dedicated iMessage line), and checking whether a number takes iMessage or SMS.
- **SMS**: text anyone from the agent's number, read and search past texts.
- **Calls**: place calls, read full transcripts, search every past call, and
  change Voice AI's voice and instructions.
- **Contact rules**: block a number for iMessage, SMS, and calls at once.

It never buys numbers or lines, releases a number, or marks someone as opted in
to SMS. Those stay with you in the Inkbox Console.

## Who can reach the agent

Only the senders on your lists. Texts and emails from anyone else are dropped
before they reach the agent, and no reply is sent.

Treat the lists like project access. The agent acts with the project's
connectors, secrets, and code, so an allowed sender can ask it to do anything
you could ask in a session. To change the lists, click **Manage**.

**Email addresses, SMS senders, and caller ID can be forged.** Inkbox doesn't
tell Machine whether an email passed sender authentication, and sender numbers
on regular phone lines (SMS and calls) can be faked. Phone numbers on iMessage
are much harder to fake. To limit the risk:

- Prefer exact addresses over whole domains.
- Use email and SMS for requests and iMessage for anything sensitive.
- The agent is told to treat email, SMS, and phone calls as requests, never as
  authority: it won't send secrets or take destructive actions on them alone.

Incoming group chats don't start sessions yet; only one-to-one texts reach the
agent. Texts like STOP, START, and HELP are handled by Inkbox and never reach
the agent.

## Asking the agent to reach you

From any session, you can ask _"text me when the deploy finishes"_ or
_"email the report to dana@acme.com"_. The agent can email any address. By SMS
it can text anyone who has opted in (in the US, texted START to its number).
By iMessage on the shared line it can text only people who have already
connected to it (step 3 above), because shared lines can't start a
conversation with someone who never texted first.

## Where credentials live

The Inkbox API key, the webhook token, and the allow-lists are
connector-scoped [secrets](/docs/project/secrets) named `INKBOX_CHANNEL_*`.
They use **Machine service** delivery, so they can be listed on the project's
Secrets page, but Machine never puts them in a sandbox. When the agent sends
a text or email, Machine attaches the key server-side.

An `INKBOX_API_KEY` you saved yourself as a Sandbox secret is separate. The
channel doesn't read or change it.

## Limits

- Inkbox allows about **100 iMessages per agent per 24 hours**. Email and call
  minutes follow your Inkbox plan, and at most 3 outbound calls run at once.
- On Inkbox's default SMS campaign, a number can text **100 different people
  per 24 hours**. For more, register your own brand and campaign (10DLC) in the
  Inkbox Console under **Phone → Compliance**. A new number needs 10-15 minutes
  before it can send SMS.
- On the shared iMessage line, the agent can't text someone before they text
  it first.
- One Inkbox agent can be connected to one Machine project at a time.

## Troubleshooting

| What you see                                     | Fix                                                                                                                   |
| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| "This key has several Inkbox agents"             | Pick the agent Machine should be, then connect again.                                                                 |
| You text and nothing happens                     | Check that your number is on the **Phone** list (**Manage**) and shows **Connected**. If it says **Not connected yet**, send `connect @handle` first. |
| You email and nothing happens                    | Check that your exact address or its domain is on the email list (**Manage**).                                        |
| You send an SMS and nothing happens              | Check that your number is on the phone list (**Manage**) and the agent has a phone number in the Inkbox Console.      |
| The agent can't text you back by SMS             | Text **START** to the agent's number once. If the number is new, wait 10-15 minutes.                                 |
| "already connected to another project"           | Disconnect Inkbox in the other project, or use a different Inkbox agent.                                              |
| The agent says it can't reach the person by text | They disconnected, or never texted first. Have them send `connect @handle` again.                                     |
| Replies stopped after you rotated the Inkbox key | Click **Disconnect**, then **Connect** again with the new key.                                                        |

To turn it off, click **Disconnect** on the Inkbox card. Machine removes its
webhook from Inkbox and deletes the stored key. Your Inkbox account and agent
are unchanged.