---
title: "Reschedule or cancel a scheduled email"
method: PATCH
path: "/emails/{id}"
tags: ["Emails"]
---

# Reschedule or cancel a scheduled email

`PATCH /emails/{id}`

## Request

- Base URL: `https://api.groundmail.dev`
- URL: `https://api.groundmail.dev/emails/{id}`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Request body

- UpdateScheduledEmailRequest
  - `scheduled_at` string, date-time
  - `scheduledAt` string, date-time: Alias for scheduled_at.
  - `cancel` boolean

## Response `200`

Scheduled email updated

- SendEmailResponse
  - `id` string, required: Public message ID (`msg_…`)
  - `status` string, required: `held` when content scanning stopped the email for review before sending (new senders only); you get `email.delivered` or `email.failed` once it is reviewed.
  - `held_back` HeldBackRecipient[]: Present only when Groundmail validation held some recipients back. The email went to the others.
    - `email` string, required: The held-back address (trimmed, lowercased)
    - `reason` 'invalid_address' | 'no_mail_server' | 'previously_bounced' | 'mailbox_not_found', required: `invalid_address`: the address cannot exist. `no_mail_server`: the domain does not exist or takes no email (no MX or A record, or a null MX). `previously_bounced`: the address hard-bounced (mailbox does not exist) for a Groundmail sender in the last 90 days. `mailbox_not_found`: Groundmail validation already knows the mailbox does not exist. The last two can be turned off per account in Settings → Suppressions.
  - `test` true: Present (and `true`) on a test send: a test key (`gm_test_…`) or only simulator addresses. Nothing was delivered; the outcome and webhooks are simulated.

## Other responses

- `400`: Email is not scheduled, or request is invalid
- `401`: Missing or invalid API key
- `404`: Email not found

---

[API](https://skmtc.dev/groundmail/apis/groundmail-api.md) · [All operations](https://skmtc.dev/groundmail/apis/groundmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/groundmail/apis/groundmail-api/revisions/479821c9fecf?raw)