# Cancel scheduled email (/api-reference/emails/cancelEmail)

`POST /emails/{id}/cancel`

Base URL: `https://next-api.useplunk.com`

Cancel a scheduled transactional email before it goes out. It is kept with status `CANCELLED`, is not billed, and a notification it held under `delivery.throttle` may be sent again straight away. This cannot be undone.

## Path parameters

- `id`: string (uuid) (required) — Email ID, as returned by `POST /v1/send`.

## Responses

### `200` — The cancelled email

- `id`: string
- `status`: enum ("SCHEDULED" | "CANCELLED" | "PENDING" | "SENDING" | "SENT" | "DELIVERED" | "OPENED" | "CLICKED" | "BOUNCED" | "COMPLAINED" | "FAILED")
- `sourceType`: enum ("TRANSACTIONAL" | "CAMPAIGN" | "WORKFLOW" | "INBOUND")
- `subject`: string
- `contact`: object
  - `id`: string
  - `email`: string
- `scheduledFor`: string | null — When a scheduled email is (or was) due.
- `sentAt`: string | null
- `createdAt`: string (date-time)

```json
{
  "id": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
  "status": "SCHEDULED",
  "sourceType": "TRANSACTIONAL",
  "subject": "Your trial ends in 3 days",
  "contact": {
    "id": "cnt_abc123",
    "email": "user@example.com"
  },
  "scheduledFor": "2026-11-01T09:00:00.000Z",
  "sentAt": null,
  "createdAt": "2026-10-25T10:30:00.000Z"
}
```

### `401` — Missing or invalid API key.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-10-25T09:19:08.207Z"
}
```

### `404` — The requested resource does not exist in this project.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-10-25T09:19:08.207Z"
}
```

### `409` — `EMAIL_NOT_SCHEDULED`: the email is already sending, sent or cancelled.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-10-25T09:19:08.207Z"
}
```

## Example request

```bash
curl -X POST 'https://next-api.useplunk.com/emails/{id}/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```