Sending

Schedule email

Send an email at a future time with scheduled_at, then reschedule or cancel it before it goes out.

Pass a scheduled_at timestamp to POST /emails to hold the email and deliver it later. The value is an ISO 8601 datetime — always send it with an explicit timezone offset (or a trailing Z for UTC) so there is no ambiguity about when it fires.

Schedule a send

When scheduled_at is in the future, MailBlastr stores the email with status scheduled and enqueues an internal job that the scheduler dispatches at the requested time. Open/click tracking, custom headers, and attachments are applied at the *actual* send time, so a scheduled email is assembled identically to an immediate one.

Emails can be scheduled up to 30 days in advance. A scheduled_at further out than that is rejected with a validation_error.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@example.com"],
  "subject": "Your weekly digest",
  "html": "<p>Here is what you missed.</p>",
  "scheduled_at": "2026-06-24T09:00:00Z"
});
console.log({ data, error });

If scheduled_at is in the past (or omitted), the email is sent immediately and starts as sent rather than scheduled.

Reschedule

Change the delivery time of a still-scheduled email with PATCH /emails/:id, passing a new scheduled_at. Only emails in the scheduled state can be rescheduled — once an email has been sent, the time is fixed.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.update('49a3999c-0ce1-4ea6-ab68-afcd6dc2e794', { "scheduled_at": "2026-06-25T09:00:00Z" });
console.log({ data, error });

Cancel

Cancel a still-scheduled email with POST /emails/:id/cancel. The email moves to canceled and the pending job is removed, so it will never be sent. Only scheduled emails can be canceled.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.cancel('49a3999c-0ce1-4ea6-ab68-afcd6dc2e794');
console.log({ data, error });

Once an email is canceled it cannot be rescheduled — submit a fresh POST /emails to send it later.

Attempting to reschedule or cancel an email that is no longer scheduled returns a validation_error — by then it has already been queued for delivery.

Scheduled email failures

A scheduled email may still fail when its run time arrives — the dispatch is attempted later than the original request, so conditions can change in between. When this happens the email moves to failed and the reason is recorded on its event log. Common causes:

The API key is no longer active — the key used to schedule the email was revoked or deleted before the run time, so MailBlastr cannot send on its behalf.
The recipient was suppressed in the meantime — if every to recipient hard-bounced, complained, or unsubscribed between scheduling and dispatch, there is no one left to deliver to.
The sending domain is no longer verified — if the from domain’s verification lapsed before the run time, the send is rejected.