> For the complete documentation index, see [llms.txt](https://docs.mailofly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailofly.com/guides/operations/mail-logs.md).

# Mail logs

**Mail logs** are the source of truth for every email Mailofly attempts to deliver — recipient, subject, status, timestamps, and error details.

**In the app:** [Mail logs](https://www.mailofly.com/user/mail-logs)

***

## What's logged

Each row represents one recipient in one send attempt:

| Field             | Description                            |
| ----------------- | -------------------------------------- |
| `to_email`        | Recipient address                      |
| `subject`         | Rendered subject (merge tags resolved) |
| `body_html`       | Rendered HTML body                     |
| `status`          | Current delivery state                 |
| `from_email`      | Sender address used                    |
| `account_id`      | Which sending account delivered        |
| `campaign_id`     | Campaign (null for Compose sends)      |
| `campaign_run_id` | Which campaign run                     |
| `contact_id`      | Linked contact record                  |
| `sent_at`         | When delivery completed                |
| `error`           | Failure message from SMTP/provider     |
| `smtp_message_id` | Provider message ID                    |

***

## Status lifecycle

```
pending → sending → sent
                 ↘ failed
                 ↘ deferred (quota — retries tomorrow)
                 ↘ halted
```

| Status     | Meaning                             | Action                                                |
| ---------- | ----------------------------------- | ----------------------------------------------------- |
| `pending`  | Queued, not yet picked up           | Wait — refresh the page                               |
| `sending`  | Currently being delivered           | Wait                                                  |
| `sent`     | Handed off successfully to provider | ✓ Done                                                |
| `failed`   | SMTP or provider rejected           | Read `error` field — fix credentials, DNS, or content |
| `deferred` | Daily account quota hit             | Sends tomorrow automatically                          |
| `halted`   | Manually stopped or system halt     | Investigate campaign state                            |

***

## Debug a failed send

1. Open [**Mail logs**](https://www.mailofly.com/user/mail-logs)
2. Filter by **status: failed** or search the recipient email
3. Click the row to open the detail panel
4. Read the **error** message — common causes:

| Error pattern         | Likely fix                                              |
| --------------------- | ------------------------------------------------------- |
| Authentication failed | Check SMTP username/password or re-auth Google          |
| SPF/DKIM fail         | Verify [DNS records](/guides/deliverability/domains.md) |
| Rate limit / quota    | Lower volume or add accounts                            |
| Invalid recipient     | Check email format / suppression                        |

***

## Filters

| Filter       | Use case                          |
| ------------ | --------------------------------- |
| Search       | Find a specific email address     |
| Campaign     | All sends for one blast           |
| Account      | Debug one sending identity        |
| Status       | Isolate failures or deferred rows |
| Campaign run | Compare runs of the same campaign |

***

## API

```bash
curl -sS "https://www.mailofly.com/api/v1/mail-logs?status=failed&page=1&page_size=50" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Accept: application/json"
```

Query parameters: `page`, `page_size` (max 100), `campaign_id`, `account_id`, `status`, `campaign_run_id`.

Full reference: [API: Mail logs](https://docs.mailofly.com/api/mail-logs)

***

## Retention

Log storage depends on your plan:

| Plan  | Stored logs  | Retention |
| ----- | ------------ | --------- |
| Free  | 5,000 rows   | 3 days    |
| Basic | 25,000 rows  | 14 days   |
| Scale | 500,000 rows | 30 days   |

Older logs are pruned automatically. Export via API if you need long-term archives.

***

## Related

* [Campaigns](/guides/campaigns-and-content/campaigns.md) — run history
* [Sending accounts](/guides/deliverability/accounts.md) — quota and deferral
* [Integrations → Webhooks](https://docs.mailofly.com/integrations/webhooks) — event notifications (roadmap)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mailofly.com/guides/operations/mail-logs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.