# Cancel a scheduled email (/docs/api-reference/emails/cancel-email)

Cancels an email sent with a future `scheduled_at` before it is sent. Canceling an already canceled email returns it unchanged. To send it at another time, reschedule it instead.

`POST https://api.coss.com/v1/emails/{id}/cancel`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Path parameters

- `id` (string, required): The email's id.

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.email.cancel("email_01k7c8m4q2f3e9v6t5r1n0p8yz");
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/emails/email_01k7c8m4q2f3e9v6t5r1n0p8yz/cancel" \
  -H "Authorization: Bearer $COSS_API_KEY"
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.email.cancel(
    id="email_01k7c8m4q2f3e9v6t5r1n0p8yz",
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &coss.CancelEmailRequest{
    ID: "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
}
client.Email.Cancel(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.email.cancel(id: "email_01k7c8m4q2f3e9v6t5r1n0p8yz")
```

PHP:

```php
<?php

use Coss\Coss;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->email->cancel(
    'email_01k7c8m4q2f3e9v6t5r1n0p8yz',
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.email.requests.CancelEmailRequest;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.email().cancel(
    "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
    CancelEmailRequest
        .builder()
        .build()
);
```

.NET:

```csharp
using Coss;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Email.CancelAsync(new CancelEmailRequest { Id = "email_01k7c8m4q2f3e9v6t5r1n0p8yz" });
```

## Response 200

The canceled email.

- `object` ("email", required)
- `id` (string, required)
- `from` (string, required): Who it's sent from.
- `to` (string[], required): The `To` addresses.
- `cc` (string[], required): The `Cc` addresses.
- `bcc` (string[], required): The `Bcc` addresses.
- `reply_to` (string[], required): The `Reply-To` addresses.
- `subject` (string, required): The subject, rendered if it came from a template.
- `html` (string | null, required): The HTML part. `null`: none, or the body was discarded.
- `text` (string | null, required): The plain text part. `null`: none, or the body was discarded.
- `headers` (map of string, required): The custom headers it was sent with.
- `tags` (object[], required): Your tags on the email.
  - `name` (string, required): The tag's name.
  - `value` (string, required): The tag's value.
- `category` (string | null, required): The email's category, which suppressions and tracking rules can scope to. `null`: none.
- `stream` ("transactional" | "marketing", required): `transactional` or `marketing`.
- `status` ("queued" | "sent" | "failed" | "scheduled" | "canceled", required): Whether the email was handed to the delivery provider. `scheduled` emails wait for `scheduled_at`; `canceled` ones were canceled before that. Per-recipient delivery is in `recipients`.
- `failure` (object | null, required): Why the email failed; `null` unless `status` is `failed`.
  - `code` (string, required): Why the email failed, e.g. `all_recipients_suppressed`, `domain_not_verified`, `content_rejected`, `attachments_unavailable`, `dispatch_failed` or `provider_error`.
  - `message` (string, required)
- `recipients` (object[], required): Each recipient, with how delivery to them went.
  - `address` (string, required): The bare, lower-cased address.
  - `type` ("to" | "cc" | "bcc", required): Which list it's on: `to`, `cc` or `bcc`.
  - `status` ("queued" | "sent" | "delivery_delayed" | "delivered" | "bounced" | "suppressed" | "complained" | "failed" | "canceled", required): Delivery status of this recipient. `suppressed` means the address is on the environment's suppression list (for every email or for this email's category), so it was skipped. `canceled` means the scheduled email was canceled before it was sent.
  - `last_event_at` (string | null, required, date-time): When its latest delivery event happened. `null`: none yet.
- `attachments` (object[], required): Attachment metadata. Content is never returned, and is discarded once sent.
  - `id` (string, required)
  - `filename` (string, required)
  - `content_type` (string, required)
  - `content_id` (string | null, required): Set for inline attachments (`cid:` references).
  - `size` (integer, required): Size in bytes.
- `sandbox` (boolean, required): True when sent from a sandbox environment (never delivered).
- `tracking` (object, required): Open and click tracking, as resolved when the email was sent, with engagement so far. Opens can be inflated by mail clients that prefetch images, clicks by link scanners.
  - `opens` (boolean, required): Whether opens are tracked for this email.
  - `clicks` (boolean, required): Whether link clicks are tracked for this email.
  - `unsubscribe` (boolean, required): Whether the email carries one-click unsubscribe headers (RFC 8058).
  - `open_count` (integer, required): Times opened. Mail clients that prefetch images inflate it.
  - `first_opened_at` (string | null, required, date-time): When it was first opened. `null`: not yet.
  - `last_opened_at` (string | null, required, date-time): When it was last opened. `null`: not yet.
  - `click_count` (integer, required): Link clicks. Link scanners inflate it.
  - `first_clicked_at` (string | null, required, date-time): When a link was first clicked. `null`: not yet.
  - `last_clicked_at` (string | null, required, date-time): When a link was last clicked. `null`: not yet.
- `created_at` (string, required, date-time)
- `sent_at` (string | null, required, date-time): When it was handed to the provider. `null`: not yet.
- `scheduled_at` (string | null, required, date-time): When the email was scheduled to be sent; `null` if it was not.
- `batch_id` (string | null, required): The batch that sent the email; `null` if it was sent on its own.
- `template` (object | null, required): The template the email was rendered from; `null` if it was sent without one.
  - `id` (string, required): The template's id.
  - `version` (integer | null, required): `null` for a dashboard test send of the draft.
  - `locale` (string, required): The locale the email was rendered in.
- `broadcast_id` (string | null, required): The broadcast the email is part of; `null` for any other email.
- `subaccount_id` (string | null, required): The sub-account the email was sent for; `null` if it was sent for none.
- `content_storage` (object, required): Whether coss.com keeps the email's content after sending it.
  - `mode` ("store" | "discard", required): The environment's content storage when the email was sent. With `discard`, the subject, `html`, `text`, `headers`, template variables and attachment filenames are cleared once the email is sent, fails or is canceled.
  - `discarded_at` (string | null, required, date-time): When the content was cleared; `null` while it is kept. A cleared email has an empty `subject`, `html` and `text` `null` and no `headers`.

Example:

```json
{
  "object": "email",
  "id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
  "from": "Acme <onboarding@acme.com>",
  "to": [
    "user@example.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "subject": "Welcome to Acme",
  "html": "<p>Thanks for signing up!</p>",
  "text": null,
  "headers": {},
  "tags": [
    {
      "name": "template",
      "value": "welcome"
    }
  ],
  "category": "onboarding",
  "stream": "transactional",
  "status": "sent",
  "failure": null,
  "recipients": [
    {
      "address": "user@example.com",
      "type": "to",
      "status": "delivered",
      "last_event_at": "2026-10-10T12:00:02.000Z"
    }
  ],
  "sandbox": false,
  "tracking": {
    "opens": false,
    "clicks": false,
    "unsubscribe": false,
    "open_count": 0,
    "first_opened_at": null,
    "last_opened_at": null,
    "click_count": 0,
    "first_clicked_at": null,
    "last_clicked_at": null
  },
  "attachments": [],
  "created_at": "2026-10-10T12:00:00.000Z",
  "sent_at": "2026-10-10T12:00:01.000Z",
  "scheduled_at": null,
  "batch_id": null,
  "template": null,
  "broadcast_id": null,
  "subaccount_id": null,
  "content_storage": {
    "mode": "store",
    "discarded_at": null
  }
}
```

## Errors

- `400`: The `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `404`: No email with this id exists in the API key's environment (`not_found`).
- `422`: The email is not scheduled (it is being sent, was sent or failed): `email_not_cancelable`.
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).