check_email_status

Look up the delivery status of an email sent earlier with send_email — timeline of events plus advice on what to do next.

check_email_status

Returns the current delivery state of a previously-sent email along with a chronologically-ordered timeline of every event we have for it (accepted, sent, delivered, bounced, complained, delayed, opened, clicked) and a short, deterministic piece of advice on what to do next.

The agent should call this whenever the user asks “did my email go through?” or whenever a follow-up flow depends on knowing whether the recipient actually got the previous message.

Scoping

• Each agent can only read back its own emails.
• If a subscriber is calling, they can only read back emails that were sent during their own session. Owner-issued emails are invisible to subscribers.

Parameters

Name	Type	Required	Description
message_id	string	yes	The message_id returned by a previous send_email call.

Returns

On success:

{
  "ok": true,
  "message_id": "...",
  "status": "delivered",
  "to": "[e-mail]",
  "cc": [],
  "bcc": [],
  "from": "<agent_name> <noreply@...>",
  "subject": "Your receipt",
  "scheduled_at": null,
  "created_at": "2026-05-19T09:31:12.412Z",
  "delivered_at": "2026-05-19T09:31:48.901Z",
  "error": null,
  "events": [
    { "type": "tool.queued",     "at": "2026-05-19T09:31:12.418Z", "summary": "Tool accepted by the platform — awaiting confirmation from the email provider." },
    { "type": "email.sent",      "at": "2026-05-19T09:31:13.882Z", "summary": "Email provider accepted the message for delivery." },
    { "type": "email.delivered", "at": "2026-05-19T09:31:48.901Z", "summary": "Recipient mail server accepted the message." }
  ],
  "advice": "Delivered successfully at 2026-05-19T09:31:48.901Z. No action needed."
}

status is one of queued, sent, delivered, bounced, complained, failed:

• queued — the platform accepted the call but the email provider hasn’t confirmed yet.
• sent — the provider has the email and is attempting delivery.
• delivered — the recipient mail server accepted the message.
• bounced — delivery failed (the timeline event distinguishes hard vs. soft).
• complained — the recipient flagged the message as spam.
• failed — the call never reached the provider (tool-level failure).

If the message_id is unknown to this agent (or belongs to a different subscriber), the tool returns:

{
  "error": "No email with message_id \"...\" was found for this agent.",
  "details": { "message_id": "...", "hint": "..." }
}

Advice — what it says, and when

advice is deterministic — purely a function of the persisted state, not LLM output. The agent can surface it directly.

Situation	Advice
failed — tool rejected the call	”Sending failed at the tool layer (reason). The email was NOT sent — no retry will happen automatically.”
bounced (hard)	“The recipient address hard-bounced (…). Do not retry to this address — pick a different contact channel.”
bounced (soft)	“The message bounced (…). Soft bounces may resolve on their own; you can retry after a few minutes if the user needs the email urgently.”
complained	”The recipient marked this message as spam. Do not email this address again from this agent.”
delivered	”Delivered successfully at … No action needed.”
scheduled_at in the future	”Held for scheduled delivery at … (in ~N minutes). Nothing to do — it will go out then.”
No provider callback yet, < 1 min old	”Accepted by the email provider but no delivery confirmation yet. Check again in a minute.”
No provider callback yet, 1–30 min old	”Accepted N minutes ago, no delivery confirmation yet. Most email arrives within a few minutes — check again shortly. If still pending after 30 minutes, treat as undelivered and consider a different channel.”
No provider callback yet, > 30 min old	”Accepted N minutes ago but the email provider never confirmed delivery. Treat as undelivered — consider another contact channel.”
delivery_delayed seen	”The recipient mail server is temporarily deferring delivery. The provider will keep retrying; check back in 15-30 minutes.”
sent seen but no delivered	”Provider has the email and is attempting delivery. No confirmation from the recipient mail server yet — usually arrives within a minute or two.”

Call from your own custom tool

export async function handle(input, ctx) {
  const sent = await ctx.tools.send_email({
    to: input.recipient,
    subject: 'Your receipt',
    body_text: input.body,
  });
  if (!sent.ok) return { sent: false, reason: sent.error };

  // poll once after a short delay
  await new Promise((r) => setTimeout(r, 5000));
  const status = await ctx.tools.check_email_status({ message_id: sent.message_id });
  return { sent: true, status: status.status, advice: status.advice };
}

async def handle(input, ctx):
    sent = await ctx.tools.send_email({
        'to': input['recipient'],
        'subject': 'Your receipt',
        'body_text': input['body'],
    })
    if not sent.get('ok'):
        return { 'sent': False, 'reason': sent.get('error') }

    import asyncio; await asyncio.sleep(5)
    status = await ctx.tools.check_email_status({ 'message_id': sent['message_id'] })
    return { 'sent': True, 'status': status['status'], 'advice': status['advice'] }

Notes

• Provider events arrive asynchronously. An immediate check_email_status right after send_email will usually show status: "queued" or "sent" — wait a few seconds and re-check for delivered.
• The full event timeline is preserved permanently — historical lookups remain accurate for old emails.
• For destructive retry decisions (re-sending after a soft bounce), gate with confirm_action + commit_action.