emailChannel()

emailChannel(options?): EmailChannelAdapter

​

Over the Email API

import { createChannelRouter, InMemoryChannelLedger } from "@telnyx/agent-harness";
import { emailChannel } from "@telnyx/agent-harness/channels";

const email = emailChannel({
  transport: env.TELNYX, // the Telnyx client; paths are relative to /v2
  inboxId: "inbox-id",
  onEvent: (event) => console.log(JSON.stringify(event)),
});

const router = createChannelRouter({
  adapters: [email],
  ledger: new InMemoryChannelLedger(),
  policy: { authorize: async () => true },
  accept: async (inbound) => ({ runId: await startRun(inbound) }),
});

// The webhook handler, after verifying the signature:
const inbound = await email.inbound(webhook.data.payload);
if (!inbound) return; // left alone: an event says why
const { runId } = await router.receive(inbound);

// Later, with the run's reply:
await router.reply({
  runId,
  serviceAccountId,
  idempotencyKey: runId,
  content: { text: "Sure, done.", messageId: inbound.content.messageId },
});

• Inbox. The inbox is the payload’s inbox_id. Without one, the adapter looks the recipient up in the account’s inbox list (GET /email_inboxes), on domainId when it is set, and keeps the list per transport for 60 seconds. A mail for another inbox than inboxId, or to another address than address, is left alone.
• Matching. The reply target is the inbox’s record of the mail. The adapter lists the inbox’s newest messages from the sender (filter[from], page[size] 10) and takes the inbound one the one whose id or message_id equals the envelope’s id or its RFC Message-ID (the live payload’s message_id_header). A Message-ID is compared without its angle brackets. The adapter never matches by subject or recency.
• Text. The text given to the model is the record’s reply_text, else the plain-text body at text_body_url with its quoted history dropped, else the message read back from its thread. A body is fetched only over https from a host in bodyHosts, through the transport first and then with plain fetch. Redirects are never followed.
• Conversation. conversationId is email-<thread id>, else email-<sender>. externalMessageId is the envelope’s id, which a redelivery repeats, so the router’s ledger treats a redelivery as a duplicate.
• Reply. send() posts { text } to POST /email_inboxes/{inbox}/messages/{message}/actions/reply with the request’s idempotency key as the Idempotency-Key header. The platform addresses and threads the reply.

​

Unavailable mail

​

EmailChannelOptions

readonly optional address?: EmailAddressScope

readonly optional bodyHosts?: readonly string[]

readonly optional domainId?: string

readonly optional fetch?: (url, init?) => Promise<Response>

readonly optional inboxId?: string

readonly optional now?: () => number

readonly optional onEvent?: (event) => void

readonly optional transport?: EmailTransport

​

EmailAddressScope

readonly optional domain?: string

readonly username: string

​

EmailTransport

get<T>(path, options?): Promise<T>

post<T>(path, options?): Promise<T>

​

EmailChannelAdapter

readonly channel: "email"

inbound(payload): Promise<EmailChannelInbound | undefined>

send(request): Promise<{ providerRequestId: string; }>

​

EmailChannelInbound

readonly channel: "email"

readonly content: EmailInboundContent

readonly conversationId: string

readonly externalMessageId: string

readonly receivedAt: number

​

EmailInboundContent

EmailInboundContent = object

readonly from: string

readonly inboxId: string

readonly messageId: string

readonly optional subject?: string

readonly text: string

readonly optional threadId?: string

readonly to: readonly string[]

​

EmailReplyContent

EmailReplyContent = object

readonly optional inboxId?: string

readonly messageId: string

readonly text: string

​

EmailChannelEvent

EmailChannelEvent = Readonly<{ type: EmailChannelEventType; } & Record<string, unknown>>

​

EmailChannelEventType

EmailChannelEventType = "unrecognised payload" | "not this agent's inbox" | "not this agent's address" | "no inbox for the recipient" | "inbox list failed" | "payload" | "message not in inbox yet" | "inbox read failed" | "body url skipped" | "body redirect skipped" | "body fetch failed" | "thread read failed" | "no text"

​

EmailInboundUnavailableError

new EmailInboundUnavailableError(message, options?): EmailInboundUnavailableError

readonly retryable: true = true

​

emailConversation()

emailConversation(mail): string

​

stripQuotedEmail()

stripQuotedEmail(text): string | undefined

​

isEmailBodyHost()

isEmailBodyHost(url, hosts?): boolean

​

EMAIL_BODY_HOSTS

const EMAIL_BODY_HOSTS: readonly string[]

​

redactUrl()

redactUrl(url): string

​

forgetEmailInboxCache()

forgetEmailInboxCache(): void