Skip to main content
Learn how to monitor your print jobs, retrieve details, track delivery, and cancel mailings when needed.

​
Retrieve a Print Job

Get complete details about a specific print job using its ID: 
import Intelliprint from 'intelliprint';

const ip = Intelliprint('your-api-key-here');

const printJob = await ip.prints.retrieve('print_abc123');

console.log('Status:', printJob.letters[0].status);
console.log('Pages:', printJob.pages);
console.log('Cost:', printJob.cost.after_tax / 100000000, 'GBP');
console.log('PDF:', printJob.letters[0].pdf);

​
List All Print Jobs

Retrieve a list of your print jobs with filtering and pagination: 
const printJobs = await ip.prints.list({
  limit: 10,
  sort_field: 'created',
  sort_order: 'desc',
  testmode: false,  // Only live mode prints
  confirmed: true   // Only confirmed prints
});

console.log(`Found ${printJobs.data.length} print jobs`);
printJobs.data.forEach(job => {
  console.log(`${job.id}: ${job.reference || 'No reference'}`);
});

​
Filtering Options

ParameterTypeDescription
limitintegerNumber of results (1-1000, default: 10)
skipintegerPagination offset (default: 0)
sort_fieldstringSort by: created, confirmed_at, reference, etc.
sort_orderstringasc or desc (default: desc)
testmodebooleanFilter by test/live mode
confirmedbooleanFilter by confirmed status
typestringletter or postcard
referencestringSearch by exact reference (case-sensitive)
letters.statusstringFilter by letter status

​
Understanding Letter Status

Each letter in a print job goes through these statuses:

​
Status Descriptions

StatusDescriptionCan Cancel?
draftUnconfirmed print job✅ Yes (delete entirely)
waiting_to_printConfirmed, queued for printing✅ Yes
printingCurrently being printed❌ No
enclosingBeing inserted into envelopes❌ No
shippingHanded to Royal Mail❌ No
sentSuccessfully delivered❌ No
cancelledCancelled before printing-
returnedReturned to sender❌ No
failed_wrong_addressAddress validation failed❌ No

​
Track Delivery Status

For tracked services, get Royal Mail tracking numbers: 
async function checkDeliveryStatus(printJobId) {
  const printJob = await ip.prints.retrieve(printJobId);
  
  for (const letter of printJob.letters) {
    console.log(`Letter ${letter.id}:`);
    console.log(`  Status: ${letter.status}`);
    
    if (letter.tracking_number) {
      console.log(`  Tracking: ${letter.tracking_number}`);
      console.log(`  Track at: https://www.royalmail.com/track-your-item`);
    }
    
    if (letter.shipped_date) {
      const shipDate = new Date(letter.shipped_date * 1000);
      console.log(`  Shipped: ${shipDate.toLocaleDateString()}`);
    }
    
    if (letter.status === 'returned' && letter.returned) {
      console.log(`  ⚠️ Returned: ${letter.returned.reason}`);
      console.log(`  Return date: ${new Date(letter.returned.date * 1000).toLocaleDateString()}`);
    }
  }
}

await checkDeliveryStatus('print_abc123');
Tracking numbers are only available for services that return a tracking reference: uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery, uk_special_delivery_9am, tracked_24, tracked_48.
Royal Mail Signed For services give a delivery scan and signature (proof of delivery), but not full end-to-end tracking like Special Delivery or Tracked 24/48.

​
Cancel a Print Job

Cancel confirmed print jobs before they’re printed: 
// Cancel entire print job
const result = await ip.prints.delete('print_abc123');

console.log('Cancellation result:', result);
// Returns updated print job with cancelled letters

// Check which letters were cancelled
result.letters.forEach(letter => {
  console.log(`${letter.id}: ${letter.status}`);
});

​
Cancellation Behaviour

For confirmed print jobs:
  • Attempts to cancel all waiting_to_print letters
  • Letters already in printing, enclosing, or shipping cannot be cancelled
  • Returns HTTP 200 with updated print job
  • You’re refunded for successfully cancelled letters
For unconfirmed (draft) print jobs:
  • Deletes the entire print job
  • Returns HTTP 202 with deletion confirmation
  • No charges involved (was never confirmed)
Partial cancellations: If some letters are already printing, only the waiting_to_print letters will be cancelled. You’ll still be charged for letters that couldn’t be cancelled.

​
Search by Reference

Use the reference field to find specific print jobs: 
// When creating, set a reference
const printJob = await ip.prints.create({
  testmode: true,
  content: '<h1>Invoice</h1>',
  recipients: [{address: {/* ... */}}],
  reference: 'Invoice INV-12345',  // Searchable reference
  confirmed: true
});

// Later, search for it
const results = await ip.prints.list({
  reference: 'Invoice INV-12345'
});

console.log('Found:', results.data.length, 'matches');
Use structured references like Invoice INV-12345 or Campaign-2024-BlackFriday to make searching easier.

​
Monitoring Workflows

​
Example: Track Campaign Delivery

async function monitorCampaignDelivery(campaignPrintJobId) {
  const printJob = await ip.prints.retrieve(campaignPrintJobId);
  
  const stats = {
    total: printJob.letters.length,
    waiting: 0,
    printing: 0,
    shipped: 0,
    delivered: 0,
    returned: 0
  };
  
  printJob.letters.forEach(letter => {
    switch (letter.status) {
      case 'waiting_to_print': stats.waiting++; break;
      case 'printing':
      case 'enclosing': stats.printing++; break;
      case 'shipping': stats.shipped++; break;
      case 'sent': stats.delivered++; break;
      case 'returned': stats.returned++; break;
    }
  });
  
  console.log('Campaign Status:');
  console.log(`  Total: ${stats.total}`);
  console.log(`  Waiting: ${stats.waiting}`);
  console.log(`  Printing: ${stats.printing}`);
  console.log(`  Shipped: ${stats.shipped}`);
  console.log(`  Delivered: ${stats.delivered}`);
  console.log(`  Returned: ${stats.returned}`);
  
  return stats;
}

​
Example: Check for Returns

async function checkForReturns() {
  const printJobs = await ip.prints.list({
    'letters.status': 'returned',
    'letters.returned.acknowledged': false,
    limit: 100
  });
  
  console.log(`Found ${printJobs.data.length} print jobs with returns`);
  
  for (const job of printJobs.data) {
    for (const letter of job.letters) {
      if (letter.status === 'returned') {
        console.log(`\n⚠️ Return Alert:`);
        console.log(`  Print Job: ${job.id}`);
        console.log(`  Reference: ${job.reference || 'N/A'}`);
        console.log(`  Recipient: ${letter.address.name}`);
        console.log(`  Reason: ${letter.returned.reason}`);
        console.log(`  Date: ${new Date(letter.returned.date * 1000).toLocaleDateString()}`);
      }
    }
  }
}

​
Pagination for Large Lists

Handle large numbers of print jobs with pagination: 
async function getAllPrintJobs() {
  let allJobs = [];
  let skip = 0;
  const limit = 100;
  let hasMore = true;
  
  while (hasMore) {
    const response = await ip.prints.list({
      limit: limit,
      skip: skip,
      sort_order: 'desc'
    });
    
    allJobs = allJobs.concat(response.data);
    
    hasMore = response.has_more;
    skip += limit;
    
    console.log(`Fetched ${allJobs.length} of ${response.total_available}`);
  }
  
  return allJobs;
}

​
Best Practices

Always set meaningful reference values when creating print jobs. This makes it much easier to find specific mailings later.
reference: `Order-${orderId}-Invoice-${invoiceNumber}`
For tracked deliveries, poll the API periodically to check status:
  • Check every few hours for standard mail
  • Check more frequently for urgent/tracked mail
  • Store print job IDs in your database for monitoring
Monitor for returned mail and update your records:
  • Update customer addresses
  • Flag problematic addresses
  • Implement retry logic or alternative contact methods
If you need to cancel, do it as soon as possible. Once printing starts, cancellation is no longer possible.

​
Next Steps

Understand Costs

Learn how costs are calculated

Errors & Troubleshooting

Handle errors and common issues

Postage & Scheduling

Learn about tracked services

API Reference

Complete API documentation