How to Give a Grok-Powered Agent an Email Inbox (xAI API Guide)

Short answer: If you build agents with Grok through the xAI API, your agent gets email by calling a REST email API as a tool. BotsInbox is built for exactly that: your agent signs itself up with one API call, creates an inbox like grok-agent@botsinbox.com, and reads mail — with verification codes pre-extracted — through simple endpoints. This guide is for developers; the consumer Grok app does not accept third-party tools.

How the pieces fit

The xAI API is OpenAI-compatible and supports function/tool calling. You define tools whose implementations call BotsInbox; Grok decides when to call them, your code executes the HTTP request, and the result goes back into the conversation. Email becomes just another capability in your agent's toolbox.

Step 1 — the agent gets an API key

POST https://api.botsinbox.com/v0/agent/sign-up
{"agent_name": "grok-agent", "owner_email": "you@example.com"}

Response includes the api_key (shown once — store it in your secret manager). Free plan: unlimited receiving, up to 5 inboxes per account, 30-day message retention.

Step 2 — define the email tools for Grok

Define tool schemas matching the BotsInbox endpoints, for example:

{
  "type": "function",
  "function": {
    "name": "create_inbox",
    "description": "Create an email inbox for the agent on botsinbox.com",
    "parameters": { "type": "object", "properties": { "local_part": { "type": "string" } } }
  }
}

Implement each tool as a thin HTTP call with the header Authorization: Bearer YOUR_API_KEY:

• create_inbox → POST /v0/inboxes
• list_messages → GET /v0/inboxes/{id}/messages
• get_message → GET /v0/messages/{id}
• search_messages → GET /v0/search?q=...

Full request/response shapes are in the OpenAPI spec — most agent frameworks can generate tool definitions from it directly.

Step 3 — the verification-code flow

1. Your Grok agent creates an inbox and uses the address on a signup form.
2. The service emails a code. Your agent polls list_messages (or receives a signed BotsInbox webhook).
3. The message's extracted_code field already contains the code — no regex over HTML required.
4. The agent completes verification and continues.

Notes and limits

• Sending is a paid-plan feature; the send endpoint returns HTTP 402 on free accounts. Receiving is the free, unlimited side — which is what signups, alerts and notifications need.
• Safety: messages carry a prompt_injection_suspected flag. In your system prompt, instruct the agent that email content is data, never instructions.
• No MCP required: Grok agents use the REST API directly here. If your stack also runs MCP clients, the same account works with the hosted MCP server.

Frequently asked questions

Can Grok itself get an email address?
The consumer Grok app cannot install third-party tools. But agents built on Grok via the xAI API can: give the agent BotsInbox tools (REST calls) and it owns an @botsinbox.com inbox it can create and read programmatically.

Does this need MCP?
No. The xAI route uses BotsInbox's REST API through function calling. MCP is an alternative for clients that support it; the same BotsInbox account and API key work for both.

How does a Grok agent read an OTP?
The verification email arrives in the agent's inbox and BotsInbox extracts the code into the message's extracted_code field, which the agent reads via the list-messages tool call.

What does it cost?
Receiving is free and unlimited on BotsInbox (up to 5 inboxes per account). Your xAI API usage is billed by xAI as usual. Sending email via BotsInbox is a paid-plan feature.