Physical mail often creates a gap in digital workflows. A notice, invoice, contract, or check arrives on paper, while the responsible team works in a CRM, document system, or remote office.
A virtual mailbox API closes that gap. It allows your application to retrieve incoming mail data, access available scans, manage automation rules, and request actions such as opening, rescanning, discarding, or shredding mail.
PostScan Mail provides a REST API for organizations that need to connect physical mail with internal software. Current API access uses an X-API-Key request header and versioned endpoints.
What Is a Virtual Mailbox API?
A virtual mailbox API connects physical mail handling with software applications.
The mailbox provider receives the physical item. The provider then creates a digital record that your application can retrieve and process.
Depending on the available data and the status of the item, that record may include:
- Mail ID
- Sender information
- Received date
- Assigned user
- Processing status
- Envelope image
- Scanned document access
Your application can use this information to update a CRM, create a task, store a document, notify a team, or initiate another mail action.
A virtual mailbox API focuses on incoming mail. This differs from direct-mail APIs that generate and send letters, postcards, or checks.
| Capability | Virtual mailbox API | Outbound mail API |
| Primary purpose | Manage incoming physical mail | Create and send physical mail |
| Typical input | Mail received at a mailbox address | Digital document or mailing job |
| Common actions | Retrieve, open, rescan, discard, shred | Print, address, mail, and track |
| Common users | Remote teams, SaaS companies, property managers | Marketing, billing, and notification teams |
| Workflow direction | Physical to digital | Digital to physical |
What Can the PostScan Mail API Do?
The current public API documentation lists three main capability groups.
Retrieve Mail Items
The GET /items endpoint retrieves items received in a PostScan Mail account.
Results can use parameters such as:
- sort_order
- page
Your application can use the returned Mail ID and item data to match records across systems.
Manage Account Automation Rules
The API includes system-rule endpoints for:
- Auto Scan
- Auto Shred
- Auto Discard
Applications can retrieve these rules and enable or disable a supported automation.
Request Actions for Mail Items
Documented address-scoped actions include:
- Open
- Cancel open
- Rescan
- Cancel rescan
- Discard
- Cancel discard
- Shred
- Cancel shred
Each action uses an address ID and one or more mail IDs. Review the current PostScan Mail API documentation before implementation because endpoints and fields may change.
How a Mail Automation Workflow Works
A custom workflow normally follows five steps.
- PostScan Mail receives a letter or package at the customer’s address.
- The platform creates a mail-item record.
- Your application retrieves the latest items through the API.
- Your business logic determines what should happen.
- Your application stores the data or requests a supported mail action.
For example, a property-management platform could retrieve new mail records and compare sender information with its vendor list.
If the sender matches an insurance company, the application could:
- Assign the record to the property manager
- Create a review task
- Store the Mail ID in the property record
- Request an open-and-scan action
- Retrieve the document after processing
Use the Mail ID as the system reference. Store processed IDs in your database so that repeated API requests do not create duplicate tasks.
PostScan Mail API Quickstart
Requirements
Before making a request, you need:
- An active PostScan Mail account
- Developer API access
- An API key
- A server-side application capable of making HTTPS requests
The API is available through the PostScan Mail Developer API. You can generate, rotate, or revoke the API key from the account dashboard.
Authentication
Send the API key through the X-API-Key header.
x-api-key: YOUR_API_KEY
Do not use a Bearer Token unless later documentation for a separate service requires one.
Keep the API key on your server. Do not expose it in browser JavaScript, public repositories, mobile application code, screenshots, or application logs.
Retrieve Mail Items
The documented base URL is:
https://api.postscanmail.com/api/account-docs/v2/
Use this request to retrieve the first page of recent items:
curl -sS -X GET “https://api.postscanmail.com/api/account-docs/v2/items?sort_order=desc&page=1” \
-H “x-api-key: YOUR_API_KEY”
Your integration should store the Mail ID, current status, and the time it processed the record.
Request That Mail Be Opened
The open action requires an address ID and a list of mail IDs.
curl -sS -X POST “https://api.postscanmail.com/api/account-docs/v2/addresses/ADDRESS_ID/items/actions/open” \
-H “x-api-key: YOUR_API_KEY” \
-H “Content-Type: application/json” \
-d ‘{“mail_ids”:[“MAIL_ID_1”]}’
Opening mail is a physical operation. Validate the address ID, mail IDs, customer permission, and requested action before sending the request.
Build a Reliable Mail Integration
A working API request is only the first step. Production integrations also need state management, error handling, and access controls.
Poll Without Creating Duplicate Work
The current public documentation lists retrieval endpoints but does not publish a webhook event catalog.
A custom integration can poll GET /items on a schedule that fits its processing needs and applicable API limits.
Use this pattern:
- Request the newest items.
- Compare each Mail ID with stored records.
- Create work only for new or changed items.
- Save the last processed state.
- Retry temporary failures without repeating completed actions.
Do not rely on received dates alone. Two items can share the same date, and item status can change after the first retrieval.
Separate Retrieval from Physical Actions
Use one process to synchronize mail data and another to request physical actions.
This separation helps prevent a failed CRM update from repeating an open, discard, or shred request.
Before requesting a destructive action:
- Confirm the Mail ID
- Confirm the address ID
- Check the current item status
- Record who or what approved the action
- Store the API response
- Limit automated shredding to approved business rules
Handle Failures by Type
Your integration should distinguish between:
- Authentication errors
- Invalid parameters
- Missing mail or address IDs
- Requests that conflict with the current item state
- Temporary server or network failures
- Usage-limit responses
Retry only temporary failures. Do not repeatedly retry invalid credentials or rejected physical actions.
API, Zapier, or Dashboard Automation
The best method depends on the required control and who maintains the workflow.
| Option | Best for | Development needed | Main advantage |
| Developer API | Custom platforms and internal systems | Yes | Full control over business logic |
| Zapier | Common app-to-app workflows | No or low | Faster setup with event-based triggers |
| Dashboard | Individual or low-volume mailbox management | No | Direct manual review |
Use the API when you need custom routing, account-level logic, database synchronization, or integration with private systems.
Use the PostScan Mail Zapier integration when you need triggers for mail, scans, AI summaries, shipments, pickups, or billing records without maintaining custom code.
Use the dashboard when someone needs to review each item before deciding what happens next.
Practical Virtual Mailbox API Use Cases
Remote-Team Mail Routing
A distributed company can synchronize mail records with its internal system and assign items based on the recipient, sender, or department.
A tax notice can create an accounting task. A contract can enter a legal review queue. An insurance document can route to operations.
Property-Mail Management
Property managers can connect incoming correspondence with property, tenant, and vendor records.
The Mail ID provides a stable reference between the mailbox record and the property-management platform.
Document Intake
A business can retrieve available scanned content and send it to an approved document-management workflow.
The downstream system can:
- Store the document
- Apply its own classification process
- Associate it with a customer record
- Request human review
- Apply the company’s retention policy
AI-Assisted Document Workflows
Mail data and scanned documents can enter an AI processing pipeline when company policy permits it.
The application might summarize a document, extract selected fields, or suggest a category. A person should review outputs before the system triggers legal, financial, or destructive actions.
Security and Postal Requirements
Protect API and Mail Data
Mail can contain personal, legal, financial, or health information.
Use these controls:
- Store API keys in a secret manager or protected environment variable
- Restrict access to the backend systems that need the key
- Rotate keys after suspected exposure
- Remove mail content from debug logs
- Encrypt stored documents
- Define retention and deletion rules
- Record requests for physical mail actions
Do not claim that an API integration makes a workflow compliant with a law or industry standard. Compliance depends on the full system, contracts, controls, jurisdiction, and use case.
USPS Form 1583 Is an Account Requirement
USPS Form 1583 authorizes a Commercial Mail Receiving Agency to receive mail for a customer.
The identity-verification and authorization process occurs during account setup. It is not completed through the current public API.
Businesses should review the current USPS Form 1583 instructions and PostScan Mail onboarding requirements before activating mail processing.
Common Implementation Mistakes
Avoid these errors:
- Sending a Bearer Token instead of x-api-key
- Using endpoint names not listed in current documentation
- Exposing an API key in client-side code
- Processing the same Mail ID more than once
- Retrying rejected physical actions without checking item state
- Assuming scan content exists before processing finishes
- Treating sender information as verified identity
- Automating shredding without approval rules
- Presenting workflow support as regulatory compliance
- Building around webhooks without a documented webhook contract
Automate Incoming Mail with PostScan Mail
A virtual mailbox API can turn incoming physical mail into data your systems can retrieve, route, and act on.
Start with a narrow workflow. Retrieve mail items. Store each Mail ID. Add one approved action. Test failure handling. Expand the integration after the first workflow works as expected.
Review the current API documentation and request Developer API access to start building.
