Cancel Scheduled Email

This endpoint allows you to cancel a scheduled email that has not been sent yet. Only emails with status ‘scheduled’ can be cancelled.

Authentication

This endpoint requires authentication via:

API key auth: Bearer token in Authorization header

Path Parameters

string

required

Unique identifier of the scheduled email to cancel.

Headers

Authorization

string

required

Bearer token for API authentication.

Request Example

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

// Cancel a scheduled email
const { data, error } = await inbound.email.sent.cancel('sch_1234567890abcdef');

if (error) {
  console.error('Error:', error);
} else {
  console.log('Email cancelled:', data.id);
  console.log('Status:', data.status);
  console.log('Cancelled at:', data.cancelled_at);
}

Response

string

required

Unique identifier of the cancelled scheduled email.

status

string

required

New status of the email (always “cancelled” for successful cancellations).

cancelled_at

string

required

ISO 8601 timestamp of when the email was cancelled.

{
  "id": "sch_1234567890abcdef",
  "status": "cancelled",
  "cancelled_at": "2024-12-24T15:30:45.123Z"
}

Usage Examples

Cancel with Error Handling

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

async function cancelScheduledEmail(emailId) {
  try {
    const { data, error } = await inbound.email.sent.cancel(emailId);
    
    if (error) {
      if (error.includes('Cannot cancel email with status')) {
        console.log('Email cannot be cancelled - it may have already been sent or failed');
      } else if (error.includes('not found')) {
        console.log('Scheduled email not found');
      } else {
        console.error('Cancellation error:', error);
      }
      return false;
    }
    
    console.log(`Email ${data.id} successfully cancelled at ${data.cancelled_at}`);
    return true;
    
  } catch (error) {
    console.error('Unexpected error:', error);
    return false;
  }
}

// Usage
const success = await cancelScheduledEmail('sch_1234567890abcdef');

Bulk Cancellation

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

async function cancelMultipleEmails(emailIds) {
  const results = [];
  
  for (const emailId of emailIds) {
    try {
      const { data, error } = await inbound.email.sent.cancel(emailId);
      
      if (error) {
        results.push({ id: emailId, success: false, error });
      } else {
        results.push({ 
          id: emailId, 
          success: true, 
          cancelled_at: data.cancelled_at 
        });
      }
    } catch (error) {
      results.push({ 
        id: emailId, 
        success: false, 
        error: error.message 
      });
    }
  }
  
  return results;
}

// Cancel multiple scheduled emails
const emailIds = ['sch_123', 'sch_456', 'sch_789'];
const results = await cancelMultipleEmails(emailIds);

const successful = results.filter(r => r.success).length;
console.log(`Successfully cancelled ${successful}/${emailIds.length} emails`);

Cancel Before Deadline

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

async function cancelIfNotTooLate(emailId, deadlineMinutes = 5) {
  // Get email details first
  const { data: email, error: getError } = await inbound.email.sent.getScheduled(emailId);
  
  if (getError) {
    console.error('Could not retrieve email:', getError);
    return false;
  }
  
  // Check if email is still scheduled
  if (email.status !== 'scheduled') {
    console.log(`Email status is ${email.status}, cannot cancel`);
    return false;
  }
  
  // Check if we're within the deadline
  const scheduledTime = new Date(email.scheduled_at);
  const now = new Date();
  const minutesUntilSend = (scheduledTime.getTime() - now.getTime()) / (1000 * 60);
  
  if (minutesUntilSend < deadlineMinutes) {
    console.log(`Too late to cancel - only ${minutesUntilSend.toFixed(1)} minutes until send`);
    return false;
  }
  
  // Cancel the email
  const { data, error } = await inbound.email.sent.cancel(emailId);
  
  if (error) {
    console.error('Cancellation failed:', error);
    return false;
  }
  
  console.log(`Email cancelled with ${minutesUntilSend.toFixed(1)} minutes to spare`);
  return true;
}

// Usage: cancel only if more than 5 minutes before send time
const cancelled = await cancelIfNotTooLate('sch_1234567890abcdef', 5);

Important Notes

Status Restrictions: Only emails with status ‘scheduled’ can be cancelled. Emails that have been sent, failed, or already cancelled cannot be cancelled.

Immediate Effect: Cancellation takes effect immediately. The scheduled email will not be sent at its scheduled time.

Access Control: You can only cancel scheduled emails that belong to your account.

Check Status First: If you’re unsure about the email’s current status, use the Get Scheduled Email endpoint first.

Get Scheduled Email

Check the status of a scheduled email before cancelling

List Scheduled Emails

View all your scheduled emails to find ones to cancel

Schedule Email

Schedule a new email for future delivery

1.0 - ✅

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

Cancel Scheduled Email

Authentication

Path Parameters

Headers

Request Example

Response

Usage Examples

Important Notes

Get Scheduled Email

List Scheduled Emails

Schedule Email

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

​Authentication

​Path Parameters

​Headers

​Request Example

​Response

​Usage Examples

​Important Notes

​Related Endpoints

Get Scheduled Email

List Scheduled Emails

Schedule Email

Authentication

Path Parameters

Headers

Request Example

Response

Usage Examples

Important Notes

Related Endpoints