n8n-nodes-easypost

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for EasyPost, the leading shipping API that aggregates 100+ carriers including USPS, UPS, FedEx, and DHL. Automate shipping workflows with label generation, rate shopping, real-time tracking, address verification, and insurance management.

Features

• Multi-Carrier Rate Shopping - Compare rates across 100+ carriers in a single API call
• Label Generation - Create shipping labels in PDF, PNG, ZPL, and EPL2 formats
• Real-Time Tracking - Track shipments across all carriers with unified status updates
• Address Verification - Validate and standardize addresses before shipping
• Insurance Management - Add shipping insurance and manage claims
• International Shipping - Full customs documentation support for international shipments
• Batch Processing - Handle high-volume label generation efficiently
• Pickup Scheduling - Schedule carrier pickups directly from your workflow
• Webhook Integration - Receive real-time notifications for tracking updates and events

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Select Install
4. Enter n8n-nodes-easypost in the input field
5. Click Install

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-easypost

# Restart n8n

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-easypost.git
cd n8n-nodes-easypost

# Install dependencies
npm install

# Build the project
npm run build

# Link to n8n
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-easypost

# Restart n8n
n8n start

Credentials Setup

EasyPost API Credentials

| Field | Description | |-------|-------------| | API Key | Your EasyPost API key |

API Key Types:

• Test Keys (start with EZTEST): Use for development and testing. Creates test labels with no real postage charges.
• Production Keys (start with EZPROD): Use for live shipping. Real labels, real charges.

To get your API key:

1. Sign up at EasyPost
2. Navigate to Account Settings → API Keys
3. Copy your Test or Production API key

Resources & Operations

Shipments

Create shipments, get rates, purchase labels, and manage the full shipping lifecycle.

| Operation | Description | |-----------|-------------| | Create | Create a new shipment and get available rates | | Get | Retrieve a specific shipment | | Get All | List all shipments with pagination | | Buy | Purchase a label using a rate ID | | Buy With Rate | Create and buy in a single call (one-call buy) | | Convert Label | Convert label to a different format | | Insure | Add insurance to a shipment | | Refund | Request a refund for unused labels | | Regenerate Rates | Get updated rates for a shipment |

Addresses

Create, verify, and manage shipping addresses.

| Operation | Description | |-----------|-------------| | Create | Create a new address (optionally verify on creation) | | Get | Retrieve an address by ID | | Get All | List all addresses | | Verify | Verify an existing address |

Parcels

Define package dimensions and weights.

| Operation | Description | |-----------|-------------| | Create | Create a parcel with custom or predefined dimensions | | Get | Retrieve a parcel by ID |

Rates

Shop for the best shipping rates across carriers.

| Operation | Description | |-----------|-------------| | Get For Shipment | Get all available rates for a shipment | | Get Smart Rates | Get rates with time-in-transit predictions |

Trackers

Track shipments across all carriers with unified status updates.

| Operation | Description | |-----------|-------------| | Create | Create a tracker for any tracking number | | Get | Retrieve tracker status | | Get All | List all trackers |

Insurance

Protect shipments with shipping insurance.

| Operation | Description | |-----------|-------------| | Create | Add insurance to a shipment | | Get | Retrieve insurance details | | Get All | List all insurance records | | Refund | Request an insurance refund |

Customs Info

Handle international shipping documentation.

| Operation | Description | |-----------|-------------| | Create | Create customs declaration with items | | Get | Retrieve customs info |

Customs Items

Define individual items for customs declarations.

| Operation | Description | |-----------|-------------| | Create | Create a customs item | | Get | Retrieve a customs item |

Batches

Process high volumes of shipments efficiently.

| Operation | Description | |-----------|-------------| | Create | Create a new batch | | Get | Retrieve batch status | | Get All | List all batches | | Add Shipments | Add shipments to a batch | | Remove Shipments | Remove shipments from a batch | | Buy | Purchase all labels in a batch | | Create Scan Form | Generate a SCAN form for the batch |

Scan Forms

Create USPS SCAN forms for batch manifesting.

| Operation | Description | |-----------|-------------| | Create | Create a scan form from shipments | | Get | Retrieve a scan form | | Get All | List all scan forms |

Pickups

Schedule carrier pickups for your shipments.

| Operation | Description | |-----------|-------------| | Create | Schedule a pickup | | Get | Retrieve pickup details | | Buy | Purchase/confirm a pickup | | Cancel | Cancel a scheduled pickup |

Carrier Accounts

Manage your carrier account connections.

| Operation | Description | |-----------|-------------| | Create | Connect a new carrier account | | Get | Retrieve carrier account details | | Get All | List all carrier accounts | | Update | Update carrier credentials | | Delete | Remove a carrier account |

Webhooks

Receive real-time notifications for shipping events.

| Operation | Description | |-----------|-------------| | Create | Create a webhook endpoint | | Get | Retrieve webhook configuration | | Get All | List all webhooks | | Update | Update webhook URL or settings | | Delete | Remove a webhook |

Usage Examples

Basic Shipment Creation

// Create a shipment and get rates
{
  "resource": "shipment",
  "operation": "create",
  "toAddress": {
    "name": "Jane Smith",
    "street1": "417 Montgomery St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US"
  },
  "fromAddress": {
    "name": "John Doe",
    "company": "Acme Corp",
    "street1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "parcel": {
    "length": 10,
    "width": 8,
    "height": 4,
    "weight": 16
  }
}

One-Call Buy (Create + Purchase)

// Create shipment and buy label in one step
{
  "resource": "shipment",
  "operation": "buyWithRate",
  "carrier": "USPS",
  "service": "Priority",
  // ... address and parcel fields
}

Rate Shopping

// Get rates from all carriers, then filter
{
  "resource": "rate",
  "operation": "getForShipment",
  "shipmentId": "shp_abc123",
  "filterByCarrier": "USPS"
}

Real-Time Tracking

// Create a tracker for any carrier
{
  "resource": "tracker",
  "operation": "create",
  "trackingCode": "9400111899223456789012",
  "carrier": "USPS"
}

International Shipment with Customs

// Create customs info for international shipping
{
  "resource": "customsInfo",
  "operation": "create",
  "certify": true,
  "signer": "John Doe",
  "contentsType": "merchandise",
  "customsItems": [
    {
      "description": "T-Shirts",
      "quantity": 5,
      "value": 25.00,
      "weight": 8,
      "hsTariffNumber": "6109.10",
      "originCountry": "US"
    }
  ]
}

Shipping Concepts

Rate Shopping

EasyPost aggregates rates from all connected carriers, allowing you to compare prices and delivery times in a single API call. The returned rates include retail and negotiated pricing when available.

Label Formats

• PDF: Best for printing on standard printers
• PNG: Image format for digital display
• ZPL: Zebra Programming Language for thermal printers
• EPL2: Eltron Programming Language for thermal printers

Predefined Packages

Common carrier packages are available as predefined options:

• USPS: FlatRateEnvelope, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox
• FedEx: FedExEnvelope, FedExPak, FedExBox
• UPS: UPSLetter, UPSExpressBox

SmartRates

SmartRates provide delivery time predictions based on historical data, offering confidence percentiles (50%, 75%, 90%, etc.) for estimated delivery.

Error Handling

The node provides detailed error information from EasyPost:

• ADDRESS.VERIFICATION.FAILURE: Address could not be verified
• RATE.UNAVAILABLE: No rates available for the shipment
• SHIPMENT.POSTAGE.FAILURE: Label purchase failed
• TRACKER.CREATE.ERROR: Tracking number not recognized

Errors include specific field information when available, helping identify exactly what needs to be corrected.

Security Best Practices

1. Use Test Keys in Development: Always use EZTEST keys during development to avoid accidental charges
2. Secure Your API Keys: Never expose API keys in client-side code or logs
3. Validate Addresses: Use address verification before creating shipments to reduce failed deliveries
4. Webhook Secrets: Configure webhook secrets to verify incoming webhook payloads

Development

# Install dependencies
npm install

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the project
npm run build

# Watch mode for development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Support

• Issues: GitHub Issues
• Documentation: EasyPost API Docs
• n8n Community: n8n Community Forum

Acknowledgments

• EasyPost for their comprehensive shipping API
• n8n for the powerful workflow automation platform
• The n8n community for their support and feedback