Inboxes

Temporary email inboxes are the core of AgentInbox. Create them on-demand, receive emails, and let them expire automatically.

Inbox Lifecycle

Every inbox has a unique email address and a TTL. After the TTL expires, the inbox and all its messages are automatically deleted.

Creating an Inbox

Create a new inbox via the API. Each inbox receives a unique email address and a time-to-live (TTL) in seconds.

bash

curl -X POST https://agentinbox.in/api/v1/inboxes \
  -H "Authorization: Bearer $AgentInbox_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds": 3600}'

typescript

import { AgentInboxClient } from "AgentInbox";
 
const client = new AgentInboxClient({
  apiKey: process.env.AgentInbox_API_KEY!,
});
 
const inbox = await client.inboxes.create({ ttlSeconds: 3600 });
console.log(inbox.emailAddress); // "k3v9x2m4q7tz@agentinbox.in"

Listing Inboxes

List all inboxes in your account. Supports pagination and filtering.

typescript

const inboxes = await client.inboxes.list({ limit: 10 });
for (const inbox of inboxes.data) {
  console.log(inbox.emailAddress);
}

Getting an Inbox

Retrieve a specific inbox by its ID.

bash

curl https://agentinbox.in/api/v1/inboxes/inb_123 \
  -H "Authorization: Bearer $AgentInbox_API_KEY"

Deleting an Inbox

Delete an inbox immediately before its TTL expires. This also removes all associated messages.

bash

curl -X DELETE https://agentinbox.in/api/v1/inboxes/inb_123 \
  -H "Authorization: Bearer $AgentInbox_API_KEY"

POST/api/v1/inboxes

Create a new temporary email inbox

Parameters

Name	Type	Required	Description
ttlSeconds	integer	Required	Time-to-live in seconds. Maximum 604800 (7 days).
metadata	object	Optional	Optional key-value metadata for tracking and filtering.
sessionId	string	Optional	Optional session ID to group this inbox into a workflow.

Responses

HTTP 201

{
  "id": "inb_123",
  "emailAddress": "k3v9x2m4q7tz@agentinbox.in",
  "status": "active",
  "ttlSeconds": 3600,
  "expiresAt": "2024-06-12T11:30:00Z",
  "createdAt": "2024-06-12T10:30:00Z"
}

TTL (Time-to-Live)

Every inbox has a TTL in seconds. After the TTL expires, the inbox is automatically deleted along with all its messages.

TTL Guidelines

Choose a TTL that fits your workflow. Short TTLs reduce resource usage and improve security.

Short flows (OTP)

300-600 seconds (5-10 minutes)

Signup flows

1800-3600 seconds (30-60 minutes)

Long-running tasks

86400 seconds (24 hours)

Maximum TTL

604800 seconds (7 days)

Metadata

Attach custom metadata to inboxes for tracking, filtering, or tagging. Metadata is a key-value object stored with the inbox.

typescript

const inbox = await client.inboxes.create({
  ttlSeconds: 3600,
  metadata: {
    workflow: "user-signup",
    userId: "usr_456",
    environment: "staging",
  },
});

Sessions

Inboxes can be grouped into sessions for tracking multi-step workflows. See the Sessions documentation for details.

typescript

const inbox = await client.inboxes.create({
  ttlSeconds: 3600,
  sessionId: "sess_789",
});

Next Steps

Messages

Receiving and reading emails

Learn more

Sessions

Group inboxes and track workflows

Learn more

API Reference

Complete endpoints and schemas

Learn more

Waits

Block until emails arrive

Learn more