List Scheduled Emails

Retrieve a paginated list of scheduled emails with optional filtering

This endpoint allows you to view all your scheduled emails, filter by status, and paginate through results.

Authentication

This endpoint requires authentication via:

• API key auth: Bearer token in Authorization header

Query Parameters

limit · integer · default: "50"

Maximum number of results to return per page. Range: 1-100.

offset · integer · default: "0"

Number of results to skip for pagination. Must be non-negative.

status · string

Filter scheduled emails by status. Available values:

• scheduled - Emails waiting to be sent
• sent - Successfully sent emails
• failed - Failed delivery attempts
• cancelled - Cancelled scheduled emails

If not provided, returns emails with all statuses.

Headers

Authorization · string · required

Bearer token for API authentication.

Request Example

Inbound SDK

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

const inbound = new Inbound('your_api_key');

// List all scheduled emails
const { data, error } = await inbound.email.sent.listScheduled();

if (error) {
  console.error('Error:', error);
} else {
  console.log('Scheduled emails:', data.data.length);
  console.log('Total:', data.pagination.total);
}

// List only pending scheduled emails
const { data: pending } = await inbound.email.sent.listScheduled({ 
  status: 'scheduled', 
  limit: 10 
});

Response

data · array · required

Array of scheduled email objects.

Show Scheduled Email Object

id · string · required

Unique identifier for the scheduled email.

from · string · required

Sender email address.

to · array · required

Array of recipient email addresses.

subject · string · required

Email subject line.

scheduled_at · string · required

ISO 8601 timestamp of when the email is/was scheduled to be sent.

status · string · required

Current status of the scheduled email (scheduled, sent, failed, cancelled).

timezone · string · required

Timezone used for scheduling the email.

created_at · string · required

ISO 8601 timestamp of when the email was scheduled.

attempts · integer · required

Number of delivery attempts made.

last_error · string

Error message from the last failed delivery attempt (only present if status is ‘failed’).

pagination · object · required

Pagination information for the current request.

Show Pagination Object

limit · integer · required

Maximum number of results requested.

offset · integer · required

Number of results skipped.

total · integer · required

Total number of scheduled emails matching the filter criteria.

hasMore · boolean · required

Whether there are more results available for pagination.

Success (200)

{
  "data": [
    {
      "id": "sch_1234567890abcdef",
      "from": "Acme <[e-mail]>",
      "to": ["[e-mail]"],
      "subject": "Scheduled Reminder",
      "scheduled_at": "2024-12-25T14:00:00.000Z",
      "status": "scheduled",
      "timezone": "America/New_York",
      "created_at": "2024-12-24T10:30:00.000Z",
      "attempts": 0
    },
    {
      "id": "sch_0987654321fedcba",
      "from": "Acme <[e-mail]>",
      "to": ["[e-mail]"],
      "subject": "Weekly Newsletter",
      "scheduled_at": "2024-12-23T09:00:00.000Z",
      "status": "sent",
      "timezone": "UTC",
      "created_at": "2024-12-22T15:45:00.000Z",
      "attempts": 1
    },
    {
      "id": "sch_abcdef1234567890",
      "from": "Acme <[e-mail]>",
      "to": ["[e-mail]"],
      "subject": "System Maintenance Alert",
      "scheduled_at": "2024-12-20T02:00:00.000Z",
      "status": "failed",
      "timezone": "UTC",
      "created_at": "2024-12-19T18:20:00.000Z",
      "attempts": 3,
      "last_error": "Recipient email address rejected by server"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 3,
    "hasMore": false
  }
}

Usage Examples

Pagination Through Results

const inbound = new Inbound('your_api_key');

// Get first page
let offset = 0;
const limit = 20;

do {
  const { data, error } = await inbound.email.sent.listScheduled({ 
    limit, 
    offset 
  });
  
  if (error) {
    console.error('Error:', error);
    break;
  }
  
  console.log(`Page ${Math.floor(offset / limit) + 1}:`, data.data.length, 'emails');
  
  // Process emails
  data.data.forEach(email => {
    console.log(`${email.subject} - ${email.status} - ${email.scheduled_at}`);
  });
  
  offset += limit;
  
  // Continue if there are more results
} while (data.pagination.hasMore);

Filter by Status

const inbound = new Inbound('your_api_key');

// Get only failed scheduled emails
const { data: failed } = await inbound.email.sent.listScheduled({ 
  status: 'failed' 
});

console.log('Failed emails:', failed.data.length);
failed.data.forEach(email => {
  console.log(`Failed: ${email.subject} - ${email.last_error}`);
});

// Get only pending scheduled emails
const { data: pending } = await inbound.email.sent.listScheduled({ 
  status: 'scheduled' 
});

console.log('Pending emails:', pending.data.length);

Monitor Scheduled Email Status

const inbound = new Inbound('your_api_key');

async function checkScheduledEmails() {
  const { data, error } = await inbound.email.sent.listScheduled({ 
    status: 'scheduled' 
  });
  
  if (error) {
    console.error('Error checking scheduled emails:', error);
    return;
  }
  
  console.log(`${data.data.length} emails scheduled`);
  
  // Show upcoming emails (next 24 hours)
  const now = new Date();
  const tomorrow = new Date(now.getTime() + 24 * 60 * 60 * 1000);
  
  const upcoming = data.data.filter(email => {
    const scheduledTime = new Date(email.scheduled_at);
    return scheduledTime <= tomorrow;
  });
  
  console.log(`${upcoming.length} emails scheduled for next 24 hours`);
}

// Check every hour
setInterval(checkScheduledEmails, 60 * 60 * 1000);

Important Notes

Real-time Updates: The status of scheduled emails is updated in real-time as emails are processed and sent.

Status Transitions: Scheduled emails progress through states: scheduled → sent (success) or scheduled → failed (after max retry attempts).

Monitoring: Use this endpoint to build dashboards and monitoring systems for your scheduled email campaigns.

1.0 - ✅