Email Scheduling

Schedule emails to be sent at a specific time in the future.

Required permission: sendEmails

POST/api/v1/emails/schedule

Schedule an email for future delivery

Request Body

to *	Recipient email address or array of addresses
subject *	Email subject line
html or text *	Email content
scheduledFor *	ISO 8601 datetime for when to send
from	Sender email (defaults to organisation setting)
replyTo	Reply-to email address

Example Request

curl -X POST "https://yourapp.com/api/v1/emails/schedule" \
  -H "Authorization: Bearer ntfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Happy New Year! 🎉",
    "html": "<h1>Happy 2025!</h1><p>Wishing you a great year ahead.</p>",
    "scheduledFor": "2025-01-01T00:00:00Z"
  }'

Response

{
  "success": true,
  "scheduledEmail": {
    "id": "507f1f77bcf86cd799439011",
    "to": "user@example.com",
    "subject": "Happy New Year! 🎉",
    "scheduledFor": "2025-01-01T00:00:00.000Z",
    "status": "pending",
    "createdAt": "2024-12-15T10:30:00.000Z"
  }
}

GET/api/v1/emails/schedule

List all scheduled emails

Query Parameters

page	Page number (default: 1)
limit	Items per page (default: 20, max: 100)
status	Filter by status: pending, sent, cancelled, failed

Example Request

curl -X GET "https://yourapp.com/api/v1/emails/schedule?status=pending" \
  -H "Authorization: Bearer ntfn_your_api_key"

Response

{
  "success": true,
  "scheduledEmails": [
    {
      "id": "507f1f77bcf86cd799439011",
      "to": "user@example.com",
      "subject": "Happy New Year!",
      "scheduledFor": "2025-01-01T00:00:00.000Z",
      "status": "pending",
      "createdAt": "2024-12-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

DELETE/api/v1/emails/schedule

Cancel a scheduled email

Query Parameters

id *	The scheduled email ID to cancel

Example Request

curl -X DELETE "https://yourapp.com/api/v1/emails/schedule?id=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer ntfn_your_api_key"

Response

{
  "success": true,
  "message": "Scheduled email cancelled successfully"
}

Email Status

pendingEmail is scheduled and waiting to be sent

sentEmail was sent successfully at the scheduled time

cancelledEmail was cancelled before it was sent

failedEmail failed to send (check error field)

Important Notes

The scheduledFor time must be in the future
Emails are processed within ±1 minute of the scheduled time
Only pending emails can be cancelled
Maximum scheduling window is 30 days in the future

curl -X POST "https://yourapp.com/api/v1/emails/schedule" \ -H "Authorization: Bearer ntfn_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "subject": "Happy New Year! 🎉", "html": "<h1>Happy 2025!</h1><p>Wishing you a great year ahead.</p>", "scheduledFor": "2025-01-01T00:00:00Z" }'

{ "success": true, "scheduledEmail": { "id": "507f1f77bcf86cd799439011", "to": "user@example.com", "subject": "Happy New Year! 🎉", "scheduledFor": "2025-01-01T00:00:00.000Z", "status": "pending", "createdAt": "2024-12-15T10:30:00.000Z" } }

{ "success": true, "scheduledEmails": [ { "id": "507f1f77bcf86cd799439011", "to": "user@example.com", "subject": "Happy New Year!", "scheduledFor": "2025-01-01T00:00:00.000Z", "status": "pending", "createdAt": "2024-12-15T10:30:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 5, "pages": 1 } }