> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "ok": true,
  "message_id": "...",
  "status": "delivered",
  "to": "alice@example.com",
  "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:

```json theme={null}
{
  "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

```js theme={null}
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 };
}
```

```python theme={null}
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`.