List Scheduled Emails

GET

api

emails

schedule

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 
});

{
  "data": [
    {
      "id": "sch_1234567890abcdef",
      "from": "Acme <noreply@yourdomain.com>",
      "to": ["customer@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["user@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["admin@example.com"],
      "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
  }
}

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

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

string

required

Unique identifier for the scheduled email.

from

string

required

Sender email address.

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

{
  "data": [
    {
      "id": "sch_1234567890abcdef",
      "from": "Acme <noreply@yourdomain.com>",
      "to": ["customer@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["user@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["admin@example.com"],
      "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 - ✅

Get Scheduled EmailRetrieve details of a specific scheduled email by ID

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 
});

{
  "data": [
    {
      "id": "sch_1234567890abcdef",
      "from": "Acme <noreply@yourdomain.com>",
      "to": ["customer@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["user@example.com"],
      "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 <noreply@yourdomain.com>",
      "to": ["admin@example.com"],
      "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
  }
}

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

List Scheduled Emails

Authentication

Query Parameters

Headers

Request Example

Response

Usage Examples

Important Notes

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

​Authentication

​Query Parameters

​Headers

​Request Example

​Response

​Usage Examples

​Important Notes

Authentication

Query Parameters

Headers

Request Example

Response

Usage Examples

Important Notes