DirectMailAmerica

Developer quickstart

Your first mailing, without spending money

Test the complete quote, preview, approval and tracking flow with synthetic credits. Simulation cannot charge a card or wallet, deduct real credits, read your inbox or send physical mail.

Create your test workspace

  1. Open Developers and choose Create a free simulation.
  2. Configure the separate simulation key securely in your MCP client. It expires in 24 hours and starts with $100 of synthetic credits.
  3. Use https://directmailamerica.com/api/mcp-simulation. Production and staging keys are rejected.

Creating another simulation replaces the previous key. Use synthetic content and addresses. Every result explicitly reports zero real funds spent and no real mail submitted.

Run three working examples

Download examples.mjs. Set DMA_SIMULATION_KEY using your shell’s secure secret mechanism, then run with Node.js 22 or later. No extra packages are required.

No-cost examples

node examples.mjs

The script saves three PDFs for review, verifies a repeated request returns the same letter, and prints the test receipts.

  1. One letter: quote_letter → review the saved PDF and total → send_letter with the quote ID, exact total, explicit approval and one request key.
  2. Two-sided postcard: quote_product → preview_product_quote → review both sides and total → send_product_quote with that saved ID and approval.
  3. Approved email: create_simulation_email → prepare_email_letter → download_email_letter → approve_email_letter with the exact current version and price.

Complete examples, expected responses and recovery instructions

Exercise failure and recovery

Use configure_simulation to select insufficient_balance, expired_quote, needs_review or rejected. Inspect the original quote or job after an uncertain result. Repeating a request never creates another test debit. Use advance_simulation_job to fabricate in-transit and delivered states.

Inspect structuredContent.operation on every result. It includes status, amounts, expiry, receipt ID and recovery instructions. A submitted or simulated-delivered order is not evidence of physical delivery.

Simulation uses real PDF composition and validation with test prices. It does not connect a real inbox, verify email senders, configure stationery or recurring automation, generate paid AI artwork, deliver webhooks, or exercise payment providers. Unsupported operations fail closed.

Ready for real mail

Choose the compact mailing connection as the default. Create a fresh real quote, review the exact artwork, addresses, options and total, and obtain explicit approval before sending.

The advanced connection adds optional email automation, stationery, workspace administration and funding workflows. Existing integrations retain their endpoints and OAuth grants. Ordinary staging prevents postage but can still spend real credits or process payments.