Agent Email Inboxes

Give your AI agent its own email address on taskmail.com. Anyone can email it, and your agent can read every message automatically — no forwarding rules, no shared logins, no workarounds.

What this unlocks Your agent can now receive notifications, updates, and requests directly by email. Set it up once and your agent will always have a dedicated inbox to monitor.

How It Works

When you create an inbox from your dashboard, two things happen:

  1. An email address like yourname@taskmail.com is reserved exclusively for your agent.
  2. An API key is generated. Your agent uses this key to retrieve messages from the inbox.

When someone sends an email to your agent's address, it is stored securely in the inbox. Your agent can then check for new messages at any time using the API key — reading them, acting on them, and optionally deleting them when done.

Creating an Inbox

1
Go to your dashboard

Log in at app.superclaws.io. Your agent must be fully set up and active before the Email Inboxes section appears.

2
Scroll to "Email Inboxes"

On your dashboard, scroll down to the Email Inboxes card. This section lets you manage all inboxes attached to your agent.

3
Choose your address

Type the name you want in the input box — for example, sarah or support-bot. Your full address will be shown as yourname@taskmail.com. Addresses are first-come, first-served, so choose something meaningful.

4
Copy your API key

Once created, your API key is displayed immediately. Copy it now — you will need it to configure your agent. The key starts with tmk_ and looks like tmk_a3f9b2....

Keep your API key private Your API key gives read and delete access to all messages in that inbox. Do not share it publicly or put it in a document others can see. If it gets compromised, delete the inbox and create a new one.

Multiple Inboxes

You can create more than one inbox per agent. This is useful if your agent handles multiple roles or workflows — for example, one inbox for customer inquiries and another for internal notifications. Each inbox gets its own address and its own API key.

API Reference

Your agent accesses its inbox through a simple HTTP API. All requests require your API key, sent as a header.

Authentication

Include your API key on every request using one of these headers:

Authorization: Bearer tmk_your_api_key_here

or

X-API-Key: tmk_your_api_key_here

Get Messages

Returns all messages in the inbox, ordered from oldest to newest. Each message includes who sent it, the subject, the full message body, and when it arrived.

GET https://app.superclaws.io/mailbox/messages

Optional filter — messages since a date:

GET https://app.superclaws.io/mailbox/messages?since=2025-06-01T00:00:00Z

Use the since parameter to only retrieve messages received after a specific date and time. Provide the date in ISO 8601 format (e.g. 2025-06-01T00:00:00Z). This is the most efficient way for your agent to check for new messages without re-reading ones it has already seen.

Example response:

{
  "mailbox": "sarah@taskmail.com",
  "messages": [
    {
      "id": "3f2b1a9e-...",
      "from_email": "boss@company.com",
      "subject": "Urgent: review this proposal",
      "text_body": "Can you take a look at the attached proposal...",
      "html_body": "<p>Can you take a look at the attached proposal...</p>",
      "received_at": "2025-06-03T14:22:10.000Z"
    }
  ]
}
Fetching only new messages Have your agent store the received_at timestamp of the last message it processed. On the next check, pass that timestamp as ?since=... to retrieve only new messages. Messages are never deleted automatically, so you stay in full control.

Get a Single Message

Retrieve a specific message by its ID.

GET https://app.superclaws.io/mailbox/messages/{message_id}

Example response:

{
  "id": "3f2b1a9e-...",
  "from_email": "boss@company.com",
  "subject": "Urgent: review this proposal",
  "text_body": "Can you take a look at the attached proposal...",
  "html_body": "<p>Can you take a look at the attached proposal...</p>",
  "received_at": "2025-06-03T14:22:10.000Z"
}

Create a Message

Inject a message directly into the inbox without sending an email. This is useful when an external service wants to push a notification or update to your agent programmatically — no email server required.

POST https://app.superclaws.io/mailbox/messages

Request body (JSON):

{
  "from_email": "notifications@myservice.com",
  "subject": "Your report is ready",
  "text_body": "The weekly report has been generated and is available for download.",
  "html_body": "<p>The weekly report has been generated and is available for download.</p>"
}

from_email is required. subject, text_body, and html_body are all optional.

Example response:

{
  "id": "8c4d2f1a-...",
  "from_email": "notifications@myservice.com",
  "subject": "Your report is ready",
  "text_body": "The weekly report has been generated and is available for download.",
  "html_body": "<p>The weekly report has been generated...</p>",
  "received_at": "2025-06-03T15:00:00.000Z"
}
When to use this vs. sending an email If you control the system that's sending the notification, use POST /mailbox/messages directly — it's faster, simpler, and doesn't require email infrastructure. If the message is coming from a third-party service that only sends emails, use your @taskmail.com address instead and let it arrive via the normal email flow.

Delete a Message

Permanently remove a single message from the inbox by its ID.

DELETE https://app.superclaws.io/mailbox/messages/{message_id}

Response:

{ "ok": true }

Delete All Messages

Permanently remove every message in the inbox at once. Useful for cleanup after your agent has processed a batch.

DELETE https://app.superclaws.io/mailbox/messages

Response:

{ "ok": true, "deleted": 12 }
Deletions are permanent There is no undo. Deleted messages cannot be recovered. If you need a record, have your agent save important messages elsewhere before deleting them.

Example: Agent That Monitors an Inbox

Here is how a typical setup looks in plain English. You can give your agent instructions like this in Telegram:

Example prompt to your agent
Every morning at 9am, check my taskmail inbox using API key tmk_a3f9b2... and tell me what new messages arrived since yesterday. For anything marked urgent in the subject line, summarise it in two sentences.

Your agent knows how to call the API, filter by date, read the results, and summarise them — you just describe what you want in plain language.

Managing Your Inboxes

From the Email Inboxes card on your dashboard you can:

  • See all your inboxes — address, message count, and API key for each.
  • Reveal or hide an API key — keys are masked by default. Click the eye icon to reveal the full key, and click again to hide it.
  • Copy an API key — click the clipboard icon to copy the full key to your clipboard, even while it is masked.
  • Regenerate an API key — click the refresh icon to issue a new key. The old key is immediately invalidated. You will be asked to confirm before the action is taken.
  • Delete an inbox — click the trash icon. This permanently deletes the inbox and all its messages. You will be asked to confirm before the action is taken. A new inbox with the same address can be created afterwards.
Lost your API key? Use the regenerate button (refresh icon) on your dashboard to issue a new key instantly. The old key is invalidated and the new one is revealed automatically. No need to delete the inbox or lose your messages.