How an agent sends, receives, replies to and forwards email from the inbox of its account, and how you put that inbox on a domain of your own. What the inbox is and what it costs is on Services.
The agent needs an account whose inbox is ready. Getting started opens one. The examples use acct_123 for the account id.
An account opened without an inbox can be given one later. From an AI client, say so:
Add an inbox to the assistant account.The client calls stack_add_account_piece with the piece inbox. The same from code or the terminal:
await stack.accounts.addPiece('acct_123', { piece: 'inbox' }, { idempotencyKey: 'add-inbox-acct-123' });npx @getstackrun/cli account add-piece acct_123 --piece inbox --idempotency-key add-inbox-acct-123From an AI client, say what to send:
Email the invoice summary to anna@example.com from the assistant account, and copy me.The client calls stack_send_account_email. The same send from code or the terminal:
import { Stack } from '@getstackrun/sdk';
const stack = new Stack();
const sent = await stack.accounts.sendEmail('acct_123', {
to: 'anna@example.com',
cc: ['you@example.com'],
subject: 'Invoice summary',
body: 'The three open invoices come to 4,200 EUR.',
});
// sent.message_id, sent.thread_id, sent.statusnpx @getstackrun/cli account send-email acct_123 \
--to anna@example.com --subject "Invoice summary" --body "The three open invoices come to 4,200 EUR."List the email the assistant account received today.The client calls stack_list_account_messages, then stack_get_account_message for one message. From code: stack.accounts.messages.list('acct_123', { channel: 'email' }). From the terminal: account messages acct_123 --channel email.
Received mail is content from outside, and so is every file attached to it. STACK scans it and flags likely attacks on every account. With controls on, flagged mail is withheld from the agent unless you choose to have it delivered with its flag.
A reply names the received email by its message id (amsg_...) and goes to the person who wrote it, in the same thread, quoting the original.
await stack.accounts.replyEmail('acct_123', 'amsg_abc', { body: 'Thanks, received.' });
await stack.accounts.forwardEmail('acct_123', 'amsg_abc', {
to: 'finance@example.com',
body: 'For your records.',
});Attach a file from the agent's drive by its id, or a small file inline. Files that arrive with an email are saved to the receiving agent's drive, so a received file can be attached to the next email by the file_id on the message.
await stack.accounts.sendEmail('acct_123', {
to: 'anna@example.com',
subject: 'Signed contract',
body: 'Attached.',
attachments: [{ file_id: 'drv_0123456789abcdef' }],
});Inline files come to at most 10 MB in all. For a larger file, upload it to the drive first.
Mail is stored when it arrives, and nothing starts the agent until a rule says so. Set one rule and each new email wakes the agent with a task:
When email arrives for the assistant account from @example.com, wake the agent to read and answer it.The client calls stack_set_wake_rule with source: "email". Each wake is one action. The task text is yours; nothing the sender wrote is part of it.
A new inbox is on STACK's shared domain. To send from your own, verify the domain once, then open accounts on it. You need to be the owner or an admin.
# 1. Connect the domain. The answer lists the DNS records to publish.
npx @getstackrun/cli account mail-domain-connect --domain mail.example.com
# 2. Publish the records at your DNS provider, then ask for the check.
npx @getstackrun/cli account mail-domain-verify omd_abcdefgh1234
# 3. See every domain and its status.
npx @getstackrun/cli account mail-domainsWhen the domain is verified, open an account on it:
await stack.accounts.open(
{ name: 'assistant', inbox: { domain: 'mail.example.com' } },
{ idempotencyKey: 'open-assistant-1' },
);A domain left unverified for 7 days can be connected by another customer.
Every field of the send, reply and forward calls is on Messages, Mail and Texts. Every tool is in the tool reference.