Scheduled Emails

Schedule emails for future delivery and manage them with list, cancel, and reschedule operations.

POST/v1/sendAPI Key

Schedule an email by including scheduledFor in the send request.

Parameter	Type	In	Description
`from`required	`string`	body	Sender email address
`to`required	`string[]`	body	Array of recipient emails
`subject`required	`string`	body	Email subject
`html`	`string`	body	HTML body
`text`	`string`	body	Plain text body
`scheduledFor`required	`string`	body	ISO 8601 datetime, must be future, max 30 days
`timezone`	`string`	body	Timezone (e.g., "America/New_York")

Request

bash

curl -X POST https://your-posthawk-instance.com/v1/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Your weekly report",
    "html": "<h1>Weekly Report</h1><p>Here are your stats...</p>",
    "scheduledFor": "2025-06-15T09:00:00Z",
    "timezone": "America/New_York"
  }'

Response

json

{
  "success": true,
  "scheduled": true,
  "id": "scheduled-uuid",
  "scheduledFor": "2025-06-15T09:00:00.000Z",
  "message": "Email scheduled successfully",
  "statusUrl": "/scheduled/scheduled-uuid"
}

GET/scheduledAPI Key

List all scheduled emails with optional filtering and pagination.

Parameter	Type	In	Description
`status`	`string`	query	Filter by status: pending, processing, sent, failed, cancelled
`limit`	`number`	query	Pagination limit
`offset`	`number`	query	Pagination offset

Response

json

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "from": "hello@yourdomain.com",
      "to": ["user@example.com"],
      "subject": "Weekly Report",
      "scheduled_for": "2025-06-15T09:00:00Z",
      "status": "pending"
    }
  ],
  "total": 1
}

GET/scheduled/:idAPI Key

Get details of a specific scheduled email.

Parameter	Type	In	Description
`id`required	`string`	path	Scheduled email UUID

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Weekly Report",
    "html": "<h1>Weekly Report</h1>...",
    "scheduled_for": "2025-06-15T09:00:00Z",
    "status": "pending",
    "created_at": "2025-06-01T12:00:00Z"
  }
}

DELETE/scheduled/:idAPI Key

Cancel a pending scheduled email.

Parameter	Type	In	Description
`id`required	`string`	path	Scheduled email UUID

Response

json

{
  "success": true,
  "data": { "id": "uuid", "status": "cancelled" },
  "message": "Scheduled email cancelled successfully"
}

PATCH/scheduled/:id/rescheduleAPI Key

Reschedule a pending email to a new time.

Parameter	Type	In	Description
`id`required	`string`	path	Scheduled email UUID
`scheduledFor`required	`string`	body	New ISO 8601 datetime

Request

bash

curl -X PATCH https://your-posthawk-instance.com/scheduled/uuid/reschedule \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{ "scheduledFor": "2025-06-20T14:00:00Z" }'

Response

json

{
  "success": true,
  "data": { "id": "uuid", "scheduled_for": "2025-06-20T14:00:00Z" },
  "message": "Email rescheduled successfully"
}

Templates

Inbound Email