# Managing emails

> The email lifecycle, every delivery status, previewing HTML/text, and reading the per-email event log.

Every email you send through MailBlastr is recorded as an **email** object with a stable `id`, the content you sent, and a `status` that advances as MailBlastr reports what happened to the message. You can [retrieve an email](https://www.mailblastr.com/docs/api/emails-get) at any time to read its current status and the full event log.

Status changes are driven by real delivery notifications (delivery, bounce, complaint) plus MailBlastr's own open/click tracking engine. Each transition is recorded once and (if you have webhooks configured) forwarded as an `email.<event>` webhook.

## Lifecycle

An email starts in one of two states depending on whether you scheduled it, then advances through delivery and engagement states as events arrive:

1. **Created** — A `POST /emails` with no `scheduled_at` is queued for delivery immediately and starts as `sent`. A `POST /emails` with a future `scheduled_at` is stored as `scheduled` and held until its run time.
2. **Sent** — The message has been accepted for delivery and is on its way. Scheduled emails enter `sent` when the scheduler dispatches them at `scheduled_at`.
3. **Delivered** — The receiving mail server accepted the message. Some messages may instead report `delivery_delayed`, `bounced`, or `complained`.
4. **Engaged** — If open/click tracking is enabled on the sending domain, the email advances to `opened` and then `clicked` as the recipient interacts with it.

## Statuses

The `status` field (and `last_event`) takes one of the following values:

| Status | Meaning |
| --- | --- |
| `queued` | Transient initial state — accepted by MailBlastr and about to be handed to the sender. Sends move through this state in milliseconds, so you will normally observe `sent` (or `scheduled`) rather than `queued`. |
| `scheduled` | Held for future delivery — `scheduled_at` is in the future. The email has not been sent yet and can still be rescheduled or canceled. |
| `sent` | Queued for delivery. This is the initial state for an immediate (non-scheduled) send. |
| `delivered` | The receiving server accepted the message. |
| `delivery_delayed` | Delivery was temporarily delayed (e.g. a transient soft bounce or a throttling/grey-listing receiver). MailBlastr may still deliver it. |
| `bounced` | The message bounced. A permanent (hard) bounce also auto-suppresses the recipient — see [Email bounces](https://www.mailblastr.com/docs/emails/bounces). |
| `complained` | The recipient marked the message as spam. The recipient is auto-suppressed — see [Email suppressions](https://www.mailblastr.com/docs/emails/suppressions). |
| `opened` | The recipient opened the email (open tracking must be enabled on the sending domain). |
| `clicked` | The recipient clicked a tracked link (click tracking must be enabled on the sending domain). |
| `canceled` | A scheduled email was canceled via [POST /emails/:id/cancel](https://www.mailblastr.com/docs/api/emails-cancel) before it was sent. |
| `failed` | The message was rejected outright (for example, the content was rejected) and it was never sent. |
| `suppressed` | The recipient was on the account suppression list, so the send to that recipient was skipped — see [Email suppressions](https://www.mailblastr.com/docs/emails/suppressions). |

> **Note:** Open and click statuses are driven by MailBlastr's own tracking engine, not by delivery notifications, so they appear only when open/click tracking is enabled for the sending domain.

## Previewing content

The retrieved email includes the exact `html` and `text` bodies you submitted, so you can preview what was sent. If you send only `text`, MailBlastr generates an HTML alternative from it; if you send only `html`, that HTML is delivered as-is. Tracking pixels and rewritten links (when tracking is enabled) are applied to the outbound message at send time and are not reflected back in the stored body.

## The event log

Each email carries an ordered `events` array — every recorded transition (`sent`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `opened`, `clicked`, `failed`) with the time it occurred. Events are de-duplicated: a redelivered notification will not record the same event twice. Fetch the log with [GET /emails/:id](https://www.mailblastr.com/docs/api/emails-get).

```json
{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794",
  "object": "email",
  "status": "delivered",
  "last_event": "delivered",
  "events": [
    { "type": "sent", "created_at": "2026-06-23T10:00:00.000Z" },
    { "type": "delivered", "created_at": "2026-06-23T10:00:04.512Z" }
  ]
}
```

> **Note:** Want events pushed to you instead of polled? Configure [webhooks](https://www.mailblastr.com/docs/webhooks/overview) to receive an `email.delivered`, `email.bounced`, `email.opened`, etc. callback as each event is recorded.