Skip to main content

​
Hybrid Mail via API (UK)

Hybrid mail lets you send physical post (letters and postcards) straight from your software, without running your own printers, envelopes, or franking machines.
With the Intelliprint hybrid mail API, you can trigger UK postal mail as easily as sending an email.

​
When to Use Hybrid Mail via API

Hybrid mail via API is a good fit when you want to:
  • Replace in-house mailrooms
    Move manual printing, enclosing, and posting out of the office and into an automated cloud service.
  • Automate transactional letters
    Send statements, policy documents, reminders, and other system-generated letters in response to events.
  • Run operational or marketing campaigns
    Combine your CRM or billing system with Intelliprint to send thousands of personalised letters at once.
  • Standardise branding and compliance
    Ensure every letter uses the right templates, backgrounds, and postage options without relying on manual steps.
If you need one-off, manual mail, use the web app instead. This guide is for engineering teams integrating Hybrid Mail via API.

​
Architecture Overview

At a high level, Intelliprint sits between your application and Royal Mail: Typical triggers include:
  • New invoice raised
  • Payment failure or arrears
  • Policy / contract changes
  • Regulatory notices
  • Marketing or lifecycle campaigns

​
Step 1: Choose Your Content Pattern

First, decide how you will generate the content for your letters: For most hybrid mail deployments, you will mix these patterns:
  • HTML for simple transactional letters
  • PDF for complex, regulatory or branded documents
  • Mailing lists + templates for marketing and operational campaigns

​
Step 2: Set Up Branding & Templates

Hybrid mail works best when your letters always look on-brand:
  • Create backgrounds and letterheads in the dashboard
    See Backgrounds & Letterheads.
  • Create templates for common letter types
    Use dashboard templates with variables for high-volume mailings, then call them from the API:     
// Node.js – trigger a hybrid mail campaign using a dashboard template
const printJob = await ip.prints.create({
  testmode: true,
  template: "tmpl_abc123",      // Template created in the dashboard
  mailing_list: "mal_abc123",   // Mailing list of recipients
  confirmed: true
});

console.log("Hybrid mail campaign job:", printJob.id);
Once you are ready to go live, remove testmode or set it to false.

​
Step 3: Integrate the API into Your Workflow

For a simple Hybrid Mail flow, your application:
  1. Detects an event (e.g. invoice generated, payment failed, status changed).
  2. Builds the content (HTML or PDF) or selects a template.
  3. Sends a prints.create request to Intelliprint.
  4. Tracks the resulting print job and letters.
Example: send a letter when an invoice is created: 
// Pseudocode – called from your billing system when an invoice is created
import Intelliprint from "intelliprint";

const ip = Intelliprint(process.env.INTELLIPRINT_API_KEY);

async function sendInvoiceLetter({ invoiceId, customer }) {
  const html = `
    <h1>Invoice ${invoiceId}</h1>
    <p>Dear ${customer.name},</p>
    <p>Your invoice is now available in your online account.</p>
    <p>Please make payment by the due date.</p>
  `;

  const printJob = await ip.prints.create({
    testmode: true, // keep true while testing
    content: html,
    recipients: [
      {
        address: {
          name: customer.name,
          line: customer.address.line,
          postcode: customer.address.postcode,
          country: customer.address.country || "GB"
        }
      }
    ],
    confirmed: true
  });

  // Store the print job ID for later tracking
  await db.invoices.update(invoiceId, {
    print_job_id: printJob.id
  });
}

​
Step 4: Test Safely with Test Mode

Hybrid mail involves real paper and postage, so testing safely matters:
  • Use testmode: true in all initial integrations.
  • Confirm print jobs (confirmed: true) to see realistic pages, envelopes, and costs.
  • Review PDFs and metadata in the dashboard.
Learn more in Test Mode and Costs.

​
Step 5: Track & Prove Delivery

For many hybrid mail use cases (especially regulatory and compliance letters), you need proof that letters were printed and dispatched.
  • Use Track, Retrieve & Cancel to:
    • Retrieve print jobs by ID
    • Check letter statuses (e.g. waiting_to_print, printing, sent, returned, failed_wrong_address)
    • Cancel jobs that have not yet been printed
  • Set up Webhooks to receive real-time updates when:
    • A letter status changes
    • A mailing list is validated
Combine this with your own logging to create a full audit trail for compliance.

​
Performance, Costs & Limits

When designing a hybrid mail integration:
  • Use templates + mailing lists for large campaigns – one API call can trigger thousands of letters.
  • Use looped HTML generation only for smaller lists where you need custom logic.
  • Use double-sided printing to reduce sheet count and lower costs, especially for multi-page letters.
See:

​
Next Steps

Pick the best starting point for your Hybrid Mail integration:

Send Your First Letter via API

HTML-based hello world letter in ~5 minutes

PDF to Post (Invoices & Statements)

Turn existing PDFs into posted mail

Bulk Campaigns from Mailing Lists

Personalised campaigns at scale

Track & Prove Delivery

Build an audit trail for hybrid mail letters