Skip to main content

Scheduling

Set scheduled_at to an RFC 3339 timestamp in the future, no more than 72 hours ahead. Epostix holds the message until it is due for dispatch.

Schedule an email​

This example uses the JavaScript SDK. It schedules one hour from the time the script runs:

import { Epostix } from '@epostix/sdk';

const apiKey = process.env.EPOSTIX_API_KEY;
if (!apiKey) throw new Error('Set EPOSTIX_API_KEY');

const client = new Epostix({ apiKey });
const scheduledAt = new Date(Date.now() + 60 * 60 * 1000);

const email = await client.emails.sendEmail({
  from: 'hello@mail.yourdomain.com',
  to: ['you@yourdomain.com'],
  subject: 'Your reminder',
  text: 'Your appointment is tomorrow.',
  scheduledAt,
}, {
  idempotencyKey: 'appointment-4821-reminder',
});

console.log(email.id, email.status);

Use your verified sender and a real recipient. In a background job, persist the timestamp and body with the job. Recomputing the timestamp on every retry changes the request and can cause an idempotency conflict.

Times and limits​

A value in the past or more than 72 hours ahead returns invalid_schedule. For a later send, keep the job in your own system and submit it closer to the time.

Use UTC with a Z suffix, or include an explicit offset. Both identify a precise instant. Convert local appointment times with the correct timezone and daylight-saving rules before making the request.

A scheduled time is the earliest dispatch time, not a promise of delivery at that instant. Queueing, throttling and the recipient's server can add delay.

Reschedule​

Use the returned email ID to update the message while it is still eligible for rescheduling:

curl -X PATCH "https://api.epostix.com/v1/emails/$EPOSTIX_EMAIL_ID" \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"scheduled_at\":\"$SCHEDULED_AT\"}"

Set EPOSTIX_EMAIL_ID to the accepted message ID and SCHEDULED_AT to a future RFC 3339 timestamp within the allowed window. A message that has moved beyond the editable state returns email_not_cancellable.

Cancel​

curl -X POST "https://api.epostix.com/v1/emails/$EPOSTIX_EMAIL_ID/cancel" \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Cancellation can stop work that has not been handed off. It cannot recall mail already sent.

Quota​

API sends reserve recipient quota when accepted, including scheduled messages. Scheduling does not bypass the daily or monthly limit. Test sends do not consume send quota.