# Canceling a scheduled send

This guide explains how to cancel or reschedule a scheduled an email or a campaign.

To try to stop an email send in progress, consult [**Stopping an in-progress send**][stop-in-progress-send].

## Cancel an email

To batch emails for later sending, the SendGrid API v3 provides a [group of endpoints][stop-scheduled-send]. To define a batch, you need to create a batch ID, then assign that ID to one or more messages. Once you define a batch, you can pause or cancel sending that batch using the API.

> \[!NOTE]
>
> You can pause or cancel no more than 10 different batches at one time.

### Generate a batch ID

To create a batch ID via the SendGrid API v3, send a [`POST /v3/mail/batch`][create-batch-id] request.

```shell
curl --request POST "https://api.sendgrid.com/v3/mail/batch" \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
     --header 'Content-Type: application/json'
```

A successful call returns an HTTP `201 Created` response header and your batch ID in a JSON block.

```json
{
  "batch_id": "YOUR_BATCH_ID"
}
```

### Assign an email to a batch

To schedule an email via the SendGrid API v3, make a [`POST /v3/mail/send`][schedule-email] request. This request must include two parameters:

* The generated batch ID (`batch_id`) you created in the preceding section.
* A UNIX timestamp (`sent_at`) for when you want this batch sent.

```shell
# !mark(10:11)
curl --request POST "https://api.sendgrid.com/v3/mail/send" \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
         "personalizations": [{
           "to": [ { "email": "john@example.com" } ],
           "subject": "Hello, World!" } ],
           "from": { "email": "from_address@example.com" },
           "content": [ { "type": "text/plain", "value": "Hello, World!" } ],
           "send_at": 1484913600,
           "batch_id": "YOUR_BATCH_ID"
       }'
```

A successful call returns an HTTP `202 Accepted` response header and no response body.

Twilio SendGrid recommends scheduling mail for "off-peak" times. As many senders schedule emails at the top of the hour or half hour, avoid those times when scheduling your batch. An example would be scheduling your send at 10:53 AM. This can lower deferral rates because your batch won't cross our servers when everyone else's mail does.

### Cancel or pause your scheduled send

To schedule an email via the SendGrid API v3, make a [`POST /v3/user/scheduled_sends`][cancel-scheduled-sends] request. You can pause or cancel a *send no later than 10 minutes before* the scheduled send time.

## Pause your batch send

To pause your scheduled send, set the parameter `"status": "pause"`.

* When you pause a batch, all messages associated with that batch stay in your sending queue.
* When a paused batch reaches its `send_at` time, SendGrid retains the messages.
* When you resume a paused batch, SendGrid delivers your scheduled send.
* When a paused batch passes 72 hours after its `send_at` time, SendGrid discards the messages as *Expired*.

```shell
# !mark(4)
curl --request POST "https://api.sendgrid.com/v3/user/scheduled_sends" \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{"batch_id": "YOUR_BATCH_ID", "status": "pause"}'
```

A successful call returns an HTTP `201 Created` response header and no response body.

## Cancel your batch send

To cancel your scheduled send, set the parameter `"status": "cancel"`.

* When cancelling a batch, all messages associated with that batch stay in your sending queue.
* When a cancelled batch reaches its `send_at` time, SendGrid discards the messages.

```shell
# !mark(4)
curl --request POST "https://api.sendgrid.com/v3/user/scheduled_sends" \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"batch_id": "YOUR_BATCH_ID", "status": "cancel"}'
```

A successful call returns an HTTP `201 Created` response header and no response body.

To discover additional features of this API, consult the [Cancel Scheduled Sends API reference][cancel-scheduled-sends-api].

## Cancel a marketing campaign

You can cancel a marketing campaign using the SendGrid UI. To cancel a legacy marketing campaign, you need to use the API.

### Use the User Interface to cancel a new marketing campaign

If you scheduled a specific time to send your campaign, you can remove it from your schedule. You might do so to make changes or reschedule the campaign.

1. Click **Marketing Campaigns** in the left-side navigation menu.
2. Click **Single Sends**.
3. Next to the Single Send you want to stop, click the dropdown menu and select **Unschedule**.

### Use the API to cancel a legacy marketing campaign

To remove a campaign from your schedule, make a [`DELETE/v3/campaigns/{campaign_id}/schedules`][unschedule-campaign] request.

The endpoint includes `{campaign_id}` as a path parameter. This ID identifies the campaign you want to unschedule.

```shell
curl --request DELETE "https://api.sendgrid.com/v3/campaigns/42/schedules" \
     --header "Authorization: Bearer $SENDGRID_API_KEY"
```

A successful unschedule returns an HTTP `204 No Content` header.

> \[!WARNING]
>
> You *can't* unschedule campaigns in the process of sending. Make a [`DELETE/v3/campaigns/{campaign_id}`][delete-campaign] request instead.

[delete-campaign]: /docs/sendgrid/api-reference/campaigns-api/delete-a-campaign

[unschedule-campaign]: /docs/sendgrid/api-reference/campaigns-api/unschedule-a-scheduled-campaign

[cancel-scheduled-sends-api]: /docs/sendgrid/api-reference/cancel-scheduled-sends

[cancel-scheduled-sends]: /docs/sendgrid/api-reference/cancel-scheduled-sends/cancel-or-pause-a-scheduled-send

[stop-in-progress-send]: /docs/sendgrid/for-developers/sending-email/stopping-an-in-progress-send

[schedule-email]: /docs/sendgrid/api-reference/mail-send/mail-send

[create-batch-id]: /docs/sendgrid/api-reference/cancel-scheduled-sends/create-a-batch-id

[stop-scheduled-send]: /docs/sendgrid/for-developers/sending-email/stopping-a-scheduled-send