Skip to content
YourMail

API reference

Cancel a scheduled email

DELETE/v1/emails/:id

A message sent with scheduledAt reads scheduled until it dispatches, and can be cancelled up to that moment. A cancelled send is never charged against your quota, because quota is charged at dispatch.

Why use this

The decision is made on the message's status, never by asking the scheduler. Cancelling a job that has already run succeeds silently at the scheduler level, so trusting that would let a message already handed to SES report as cancelled. A 409 here means it genuinely went.

For example

A reminder is scheduled for the morning a trial ends. The customer upgrades the night before, and your upgrade handler cancels the reminder by id.

Example

import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);

const { id } = await yourmail.send({
  from: "hello@mail.acme.com",
  to: "alice@example.com",
  subject: "Your trial ends tomorrow",
  html: "<p>...</p>",
  scheduledAt: "2026-09-10T09:00:00Z",
});

// Alice upgraded overnight — don't send it.
const { canceled } = await yourmail.cancel(id); // true

Response

// 200 OK
{ "id": "jn7abc...", "canceled": true }

// 409 Conflict — it has already gone
{
  "error": {
    "type": "validation_error",
    "message": "This email is sent and can no longer be cancelled. Only a scheduled send that has not dispatched can be.",
    "docs_url": "https://yourmail.dev/docs/errors#validation_error"
  }
}

The message's status becomes canceled — its own value rather than a reuse of failed, which the dashboard explains to a customer as a delivery problem. No webhook fires for a cancellation. The SDK does not retry a 409: "it has already gone" is not an ambiguous failure.

Errors

See Errors for the full error shape.

401authentication_error

The API key is missing, malformed or revoked

403authentication_error

The key is send-only. Cancelling mail is not sending it, so a key made to be pasted into an agent cannot do it

404not_found

No email with that id on this account

409validation_error

The message is not scheduled — it has dispatched, failed, or was already cancelled