Email API

Provision email identities, send and receive emails, and manage threads through the Trunx API.

Email identities are backed by AgentMail. Each identity gets a dedicated inbox that can send, receive, and reply to emails. Assign an AI agent to an identity for automatic responses.

Identities

Create Identity

POST /api/email/identities

Provision a new email identity.

Field	Type	Required	Description
`localPart`	string	Yes	Local part of the email address (e.g. `support`)
`domain`	string	No	Domain (defaults to `agentmail.to`)
`displayName`	string	No	Display name for the identity
`agentId`	string	No	Agent ID for automatic email responses

curl -X POST https://api.trunx.ai/api/email/identities \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "localPart": "support",
    "displayName": "Support Team"
  }'

const res = await fetch("https://api.trunx.ai/api/email/identities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    localPart: "support",
    displayName: "Support Team",
  }),
});
const identity = await res.json();

import requests

res = requests.post(
    "https://api.trunx.ai/api/email/identities",
    headers={"Authorization": "Bearer tk_live_..."},
    json={
        "localPart": "support",
        "displayName": "Support Team",
    },
)
identity = res.json()

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "address": "support@agentmail.to",
  "localPart": "support",
  "domain": "agentmail.to",
  "displayName": "Support Team",
  "agentId": null,
  "status": "active",
  "smtpHost": "smtp.agentmail.to",
  "smtpPort": 465,
  "smtpUser": "support@agentmail.to",
  "smtpPass": null,
  "createdAt": "2026-03-15T12:00:00.000Z"
}

List Identities

GET /api/email/identities

Returns all email identities for your account.

{
  "identities": [
    {
      "id": "a1b2c3d4-...",
      "address": "support@agentmail.to",
      "localPart": "support",
      "domain": "agentmail.to",
      "displayName": "Support Team",
      "agentId": null,
      "status": "active",
      "smtpHost": "smtp.agentmail.to",
      "smtpPort": 465,
      "smtpUser": "support@agentmail.to",
      "smtpPass": null,
      "createdAt": "2026-03-15T12:00:00.000Z"
    }
  ]
}

Get Identity

GET /api/email/identities/{id}

Returns a single identity by ID.

Configure Identity

PATCH /api/email/identities/{id}

Update identity settings, including agent assignment.

Field	Type	Required	Description
`displayName`	string \| null	No	Update display name
`agentId`	string \| null	No	Assign an agent (`null` to unassign)

curl -X PATCH https://api.trunx.ai/api/email/identities/a1b2c3d4-... \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent-uuid-here"}'

When an agent is assigned, inbound emails trigger an automatic AI response. The agent uses its textModel to generate replies and has access to cross-channel context (SMS history, call transcripts, knowledge bases) based on its contextSources configuration.

Delete Identity

DELETE /api/email/identities/{id}

Deprovisions the email identity and removes it from AgentMail.

{
  "status": "deprovisioning"
}

Messaging

Send Email

POST /api/email/identities/{id}/send

Send an email from the specified identity.

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`subject`	string	Yes	Email subject line
`body`	string	Yes	Email body (plain text)

curl -X POST https://api.trunx.ai/api/email/identities/a1b2c3d4-.../send \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your order has shipped",
    "body": "Hi! Your order #1234 has shipped and should arrive by Friday."
  }'

const res = await fetch("https://api.trunx.ai/api/email/identities/a1b2c3d4-.../send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "customer@example.com",
    subject: "Your order has shipped",
    body: "Hi! Your order #1234 has shipped and should arrive by Friday.",
  }),
});
const data = await res.json();

res = requests.post(
    "https://api.trunx.ai/api/email/identities/a1b2c3d4-.../send",
    headers={"Authorization": "Bearer tk_live_..."},
    json={
        "to": "customer@example.com",
        "subject": "Your order has shipped",
        "body": "Hi! Your order #1234 has shipped and should arrive by Friday.",
    },
)
data = res.json()

Response

{
  "messageId": "msg_abc123",
  "threadId": "thread_xyz789"
}

Reply to Thread

POST /api/email/identities/{id}/reply

Reply to an existing email thread.

Field	Type	Required	Description
`threadId`	string	Yes	Thread ID to reply to
`body`	string	Yes	Reply body (plain text)

curl -X POST https://api.trunx.ai/api/email/identities/a1b2c3d4-.../reply \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thread_xyz789",
    "body": "Thanks for your reply! Let me look into that for you."
  }'

Response

{
  "messageId": "msg_def456",
  "threadId": "thread_xyz789"
}

Threads

List Threads

GET /api/email/identities/{id}/threads

List email threads for an identity.

Parameter	Type	Required	Description
`limit`	number	No	Max threads to return
`cursor`	string	No	Pagination cursor

{
  "threads": [
    {
      "threadId": "thread_xyz789",
      "subject": "Order #1234 question",
      "participants": ["customer@example.com", "support@agentmail.to"],
      "messageCount": 3,
      "lastMessageAt": "2026-03-15T14:30:00.000Z"
    }
  ],
  "nextCursor": "cursor_abc..."
}

Get Thread

GET /api/email/identities/{id}/threads/{threadId}

Get a thread with all its messages.

{
  "threadId": "thread_xyz789",
  "subject": "Order #1234 question",
  "participants": ["customer@example.com", "support@agentmail.to"],
  "messageCount": 3,
  "lastMessageAt": "2026-03-15T14:30:00.000Z",
  "messages": [
    {
      "messageId": "msg_001",
      "threadId": "thread_xyz789",
      "from": "customer@example.com",
      "to": ["support@agentmail.to"],
      "subject": "Order #1234 question",
      "body": "Hi, when will my order arrive?",
      "sentAt": "2026-03-15T12:00:00.000Z"
    },
    {
      "messageId": "msg_002",
      "threadId": "thread_xyz789",
      "from": "support@agentmail.to",
      "to": ["customer@example.com"],
      "subject": "Re: Order #1234 question",
      "body": "Hi! Your order should arrive by Friday.",
      "sentAt": "2026-03-15T12:01:00.000Z"
    }
  ]
}

Inbound Email

Inbound emails are delivered via webhooks. Configure a webhook with the email.received event, or assign an AI agent to the identity for automatic responses.

{
  "event": "email.received",
  "data": {
    "identityId": "a1b2c3d4-...",
    "from": "customer@example.com",
    "to": "support@agentmail.to",
    "subject": "Question about my account",
    "threadId": "thread_abc123",
    "messageId": "msg_xyz789"
  }
}

When an identity has an assigned agent, inbound emails are automatically answered. The agent's response is sent as a reply to the same thread. You'll receive both email.received and email.agent.response events.

Agent Auto-Response

Email identities support the same hub-and-spoke agent pattern as SMS. When you assign an agent to an identity:

Inbound email arrives at the identity's address
The system loads the agent's configuration and builds context from contextSources (SMS history, call transcripts, knowledge bases)
The agent's textModel generates a response using the enriched prompt
The response is sent as a reply to the original thread

To enable agent auto-response, the agent must have a textModel configured (e.g. claude-haiku-4-5-20251001 or gpt-4o).

# 1. Create an agent with a textModel
curl -X POST https://api.trunx.ai/api/agents \
  -H "Authorization: Bearer tk_live_..." \
  -d '{"name": "email-support", "systemPrompt": "You are a helpful support agent...", "textModel": "claude-haiku-4-5-20251001", "contextSources": ["sms", "calls", "knowledge"]}'

# 2. Assign the agent to an email identity
curl -X PATCH https://api.trunx.ai/api/email/identities/a1b2c3d4-... \
  -H "Authorization: Bearer tk_live_..." \
  -d '{"agentId": "agent-uuid-here"}'

On this page