Email warmup API for sender schedules and delivery results

An email warmup API lets your application manage a sender's gradual sending schedule and review the results. MailSlurp sends paced messages through a connection you own, records delivery activity, and provides separate provider placement checkpoints where your coverage includes them.

Use the email warmup product for a dashboard walkthrough, or follow the warmup API setup to create and control a program through REST.

Connect the sender you want to warm

Start with a verified sending connection. MailSlurp supports authenticated SMTP and supported provider API connections; the connection's credentials and From address define the sending path. The SMTP warmup guide walks through connection verification and test delivery.

Authenticate the domain with SPF, DKIM and DMARC before starting. Use a sender you control and permission-based sending practices. Warmup activity complements those foundations and does not guarantee that future campaigns will reach every recipient's inbox.

Create a schedule and control its progress

Create a program with POST /email-warmup/programs. Choose the sender connection, new-sender or recovery goal, current and target daily volume, ramp duration, maintenance settings, time zone and local sending window.

The response includes the program id, status, blockers and version. Creating the program does not mean a message has been sent. Start it separately after reviewing its configuration and resolving any blockers.

Task	API request
Create a program	POST /email-warmup/programs
Read current status	GET /email-warmup/programs/{programId}
Start the program	POST /email-warmup/programs/{programId}/start
Pause or resume	POST /email-warmup/programs/{programId}/pause or /resume
Stop the program	POST /email-warmup/programs/{programId}/stop
Inspect delivery activity	GET /email-warmup/programs/{programId}/analytics
Review readiness	GET /email-warmup/programs/{programId}/readiness
Read placement checkpoints	GET /email-warmup/programs/{programId}/placement-checks

Control requests use an expectedVersion body. Read the latest program before issuing a command so a stale application process cannot silently overwrite a newer decision. Available transitions depend on the current status; a rejected command needs investigation rather than an automatic retry loop.

Read the result your application needs

This Node.js example reads a program you have already created. Set MAILSLURP_API_KEY and MAILSLURP_WARMUP_PROGRAM_ID in your environment and use Node.js 20 or later.

const apiKey = process.env.MAILSLURP_API_KEY;
const programId = process.env.MAILSLURP_WARMUP_PROGRAM_ID;
if (!apiKey || !programId) throw new Error("Set the API key and warmup program ID");

async function readWarmup(path) {
  const response = await fetch(`https://api.mailslurp.com${path}`, {
    headers: { "x-api-key": apiKey },
    signal: AbortSignal.timeout(30000),
  });
  if (!response.ok) throw new Error(`Warmup API returned ${response.status}`);
  return response.json();
}

const path = `/email-warmup/programs/${encodeURIComponent(programId)}`;
const [program, activity] = await Promise.all([
  readWarmup(path),
  readWarmup(`${path}/analytics?days=7`),
]);

console.log({
  status: program.status,
  blockers: program.blockers,
  acceptedSends: activity.totalAcceptedSends,
  observedReceipts: activity.totalObservedSends,
  failedSends: activity.totalFailedSends,
  placementChecks: activity.placementChecks,
});

The counters answer different questions. totalAcceptedSends records provider acceptance. totalObservedSends records observed warmup delivery. placementChecks contains the separate provider checks. A newly started program may have no observed activity yet; wait for its scheduled window and inspect status before concluding that delivery failed.

For the complete create-and-start request, see automating a warmup program. The OpenAPI reference defines current request fields and response types.

Choose the next action from the evidence

Read readiness alongside activity. The readiness response includes a status, summary, pacing information and recommendations. A program waiting outside its sending window needs a different response from one paused because its connection is no longer verified.

If sending fails repeatedly, verify the connection and sender identity. If provider placement worsens, inspect authentication, content and the affected provider before increasing volume. Keep normal campaign traffic in view when deciding the sender's total daily workload.

Run a separate inbox placement test for the real campaign or transactional message. Controlled warmup receipt, SMTP acceptance and a low spam score do not establish its inbox or spam placement.

Keep product email working while the sender changes

A warmup program measures sender activity and delivery signals. For signup, password reset or verification messages, add email integration tests that receive the actual message and complete the application action. Use domain monitoring to catch authentication changes between checks.

Questions about the warmup API

Can I use the dashboard and API for the same program?

Yes. Use the dashboard to connect the sender and inspect its results, then use the program ID in your application. Read the latest version before a control command so dashboard and API changes stay coordinated.

Does starting a program prove that delivery succeeded?

Starting initiates the program's next eligible actions. Inspect status and blockers, then review accepted sends, observed delivery and any completed provider checkpoints. An unfinished or missing checkpoint remains unknown.

Can I pause a program when my checks fail?

Yes. Read the current program and submit a pause command with its version as expectedVersion. Investigate the cause before resuming. A system-paused program can require a different recovery action from a customer-paused program; the current status and API response explain the next step.

How do I get started?

Start email warmup, verify your sending connection, and follow the warmup documentation to choose a schedule and coverage.