Skip to main content
Learn how to fine-tune address placement when using pre-inserted addresses in PDFs to ensure perfect alignment with envelope windows.

​
When to Use Nudging

Nudging is useful when:
  • Addresses in your PDF don’t quite line up with envelope windows
  • You need to adjust positioning by a few millimeters
  • Different printers or PDF generators produce slightly different output
  • You want precise control over address placement
Only for pre-inserted addresses: Nudging only works when addresses are already in your PDF. It doesn’t apply to dynamic addresses added by Intelliprint.

​
How Nudging Works

Nudging shifts the entire document content by specified millimeters:
  • X axis: Positive moves right, negative moves left
  • Y axis: Positive moves down, negative moves up

​
Basic Usage

import Intelliprint from 'intelliprint';
import fs from 'fs';

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

const printJob = await ip.prints.create({
  testmode: true,
  
  // PDF with pre-inserted addresses
  file: fs.createReadStream('./letters-with-addresses.pdf'),
  
  // Adjust address position
  nudge: {
    x: 2,    // Move 2mm to the right
    y: -1    // Move 1mm up
  },
  
  confirmed: true
});

​
Standard Envelope Window Positions

Know where your envelope windows are to position addresses correctly:

​
Left Window Envelope (Default)

┌─────────────────────────────┐
│                             │
│  ┌─────────────┐            │
│  │   Address   │            │
│  │   Window    │            │
│  └─────────────┘            │
│                             │
│                             │
└─────────────────────────────┘

Position: 20mm from left, 45mm from top
Size: Approximately 90mm x 35mm

​
Right Window Envelope

┌─────────────────────────────┐
│                             │
│           ┌─────────────┐   │
│           │   Address   │   │
│           │   Window    │   │
│           └─────────────┘   │
│                             │
│                             │
└─────────────────────────────┘

Position: 90mm from left, 45mm from top
Size: Approximately 90mm x 35mm

​
Testing Your Nudge Values

1

Create a test print

Start with no nudging to see the default position:
const test = await ip.prints.create({
  testmode: true,
  file: fs.createReadStream('./letters.pdf'),
  // No nudge parameter
  confirmed: true
});
2

Download and review PDF

Download the generated PDF from test.letters[0].pdf and check if the address shows correctly in the window area.
3

Adjust if needed

If the address is slightly off, apply nudging:
  • Too far left? Use positive X (move right)
  • Too far right? Use negative X (move left)
  • Too low? Use negative Y (move up)
  • Too high? Use positive Y (move down)
4

Test again

Create another test print with your nudge values and verify the positioning.

​
Common Nudge Scenarios

​
Scenario 1: Address Too Far Left

// Move address 3mm to the right
nudge: {
  x: 3,
  y: 0
}

​
Scenario 2: Address Too Low

// Move address 2mm up
nudge: {
  x: 0,
  y: -2
}

​
Scenario 3: Diagonal Adjustment

// Move 2mm right and 1mm up
nudge: {
  x: 2,
  y: -1
}

​
Choosing Window Side

Control which side of the envelope the address window appears: 
const printJob = await ip.prints.create({
  testmode: true,
  file: fs.createReadStream('./letters.pdf'),
  
  // Choose window position
  address_window: 'left',  // or 'right'
  
  // Adjust for chosen window
  nudge: {
    x: 2,
    y: -1
  },
  
  confirmed: true
});
Options:
  • left (default): Window on left side of envelope
  • right: Window on right side of envelope
Different window positions may require different nudge values. Test both if you’re unsure which your PDF design suits best.

​
Real-World Example: Generated Invoices

import Intelliprint from 'intelliprint';
import fs from 'fs';

async function sendInvoicesWithPerfectAddressing(invoices) {
  // We've tested and found our invoice generator
  // positions addresses 1mm too far left and 0.5mm too high
  const NUDGE_SETTINGS = {
    x: 1,      // Move 1mm right
    y: 0.5     // Move 0.5mm down
  };
  
  const printJobs = [];
  
  for (const invoice of invoices) {
    const printJob = await ip.prints.create({
      testmode: false,
      
      // Generated invoice PDF with address
      file: fs.createReadStream(`./invoices/${invoice.number}.pdf`),
      
      // Apply consistent nudge for our generator
      nudge: NUDGE_SETTINGS,
      
      // Use left window
      address_window: 'left',
      
      postage: {
        service: 'uk_first_class'
      },
      
      reference: `Invoice ${invoice.number}`,
      confirmed: true
    });
    
    printJobs.push({
      invoice_number: invoice.number,
      print_job_id: printJob.id
    });
  }
  
  return printJobs;
}

​
Advanced: Per-Letter Nudging

For print jobs with multiple letters that need different adjustments: 
// Note: This requires updating the print job after creation
// Each letter can have its own nudge settings

const printJob = await ip.prints.create({
  testmode: true,
  file: fs.createReadStream('./multiple-letters.pdf'),
  splitting: {
    method: 'split_on_phrase',
    phrase: 'Dear'
  }
});

// Update specific letters with different nudge values
// This would require API support for per-letter nudging
// Currently, nudge applies to all letters in a print job
Currently, nudge settings apply to all letters in a print job. Contact support if you need per-letter nudging capabilities.

​
Precision and Limits

  • Precision: Values can be decimals (e.g., 1.5, 0.25)
  • Reasonable range: ±10mm typically covers most adjustments
  • Units: Always in millimeters
// Valid nudge examples
nudge: { x: 1.5, y: -0.5 }    // Small precise adjustment
nudge: { x: 5, y: -3 }         // Larger adjustment
nudge: { x: 0, y: 2 }          // Only vertical adjustment
nudge: { x: -2, y: 0 }         // Only horizontal adjustment

​
Troubleshooting

Possible causes:
  • Address positioned outside the window area in your PDF
  • PDF margins pushing content too far
  • Wrong window side selected (left vs right)
Solutions:
  • Check your PDF address position (should be 20mm from left, 45mm from top for left window)
  • Try adjusting with larger nudge values
  • Download test PDF to verify positioning
Check:
  • Are you using pre-inserted addresses? (Nudging doesn’t work with dynamic addresses)
  • Is the PDF format supported?
  • Are nudge values within reasonable range?
Try:
  • Test with testmode: true first
  • Start with small values (±2mm) and adjust
  • Verify in the PDF preview
Common causes:
  • Different PDF generators produce slightly different output
  • Printer/software variations
  • Font rendering differences
Solution:
  • Use consistent PDF generation tools
  • Test thoroughly before bulk sending
  • Store nudge values that work for your setup

​
Best Practices

Always create a test print with testmode: true before sending real mail to verify address positioning.
Once you find nudge values that work for your PDF generator, document them:
// Store in config
const COMPANY_LETTERHEAD_NUDGE = { x: 2, y: -1 };
const INVOICE_NUDGE = { x: 1.5, y: 0 };
Use the same PDF generation tools and settings to ensure consistent address positioning across all mailings.
If you have flexibility in your PDF design, design for the default left window to avoid needing nudge adjustments.

​
Next Steps

PDF + Split Quickstart

Learn more about PDFs with pre-inserted addresses

Coversheet Tutorial

Alternative: Let Intelliprint handle addresses

Postage & Envelopes

Choose envelope sizes and services

API Reference

Full nudging API documentation