DirectMailAmerica MCP

Your agent. Real mail.

Get quotes, prepare letters and manage Email to Letter through MCP. Connect once, check your account and permissions, then send only with your authorization.

Plugin v1.0.0 includes the hosted MCP connection and mailing workflow. The ZIP is available now. A shared ChatGPT/Codex directory installation link will appear after review and publication.

Connect to the hosted endpoint

Use a client that supports Streamable HTTP. Enter this exact endpoint:

https://directmailamerica.com/api/mcp

  1. In ChatGPT, add a custom MCP connection where developer mode is available; in Codex, add the MCP URL or install the plugin. Other MCP clients can use the configuration below.
  2. Public tools work without signing in. For account tasks, choose Connect account and authorize the requested permissions on DirectMailAmerica. Enter your existing workspace key on that secure page. Clients that support custom headers can use Authorization: Bearer <workspace key> instead.
  3. Run get_connection_status. Confirm the workspace, account owner, key environment and permissions before accessing history or sending mail.

Create a key in your workspace’s Developers page. Browser sign-in alone does not connect MCP. Keep keys in the client’s secret settings or an environment variable; never put them in prompts, URLs or shared plugin files.

Public / OAuth MCP connection

{
  "mcpServers": {
    "directmailamerica": {
      "type": "streamable-http",
      "url": "https://directmailamerica.com/api/mcp"
    }
  }
}
Codex with an existing workspace key

config.toml

[mcp_servers.directmailamerica]
url = "https://directmailamerica.com/api/mcp"
bearer_token_env_var = "DIRECTMAILAMERICA_API_KEY"

Set DIRECTMAILAMERICA_API_KEY securely in the process environment. For OAuth, omit bearer_token_env_var and use codex mcp login directmailamerica.

Public information and account operations

Public — no account, no charge

Endpoint and tool discovery, product specifications, standard price quotes, connection checking and login instructions. An anonymous connection cannot read your workspace, inbox, balance or jobs.

Authenticated — workspace access

OAuth uses explicit consent, PKCE and tokens bound to this endpoint. You can grant read, edit, paid-send and admin access separately. API keys have the workspace owner’s privileges. Email to Letter changes need a production key; global polling also requires an administrator.

Guest x402 mailing and card funding can work without account login, but payments are real and do not inherit a browser account. Production sends can spend credits and buy postage. Staging keys prevent postage; they can still spend credits or make real payments.

Verify the connection before acting

get_connection_status is free. It returns whether the connection is authenticated, which workspace and owner the credential represents, its environment, granted permissions and a tool-by-tool access check. It never sends mail or reveals credentials.

Connection check

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_connection_status",
    "arguments": {}
  }
}

Install the bundled workflow

The plugin directs Direct Mail America tasks through MCP, explains missing connections before website signup, verifies account access, and requires approval of artwork, addresses and the total before paid mailing. It also covers inbox provisioning, rules, previews, downloads, deletion and safe retries.

Download the installable plugin ZIP · Read the bundled instructions · Full MCP documentation

Install from a local Codex marketplace today

Download and register marketplace

mkdir -p dma-agent-marketplace/plugins/directmailamerica
curl -fL https://directmailamerica.com/plugins/directmailamerica.zip -o dma-plugin.zip
unzip dma-plugin.zip -d dma-agent-marketplace/plugins/directmailamerica
mkdir -p dma-agent-marketplace/.agents/plugins
curl -fL https://directmailamerica.com/agents/marketplace.json -o dma-agent-marketplace/.agents/plugins/marketplace.json
codex plugin marketplace add ./dma-agent-marketplace

Then open the app’s Plugins directory, choose the DirectMailAmerica marketplace and install the plugin. Restart the desktop app if the new marketplace is not shown. This local installation is separate from OpenAI’s shared directory review.

Tools, access and charges

Read the description before calling a tool. Quotes do not authorize sending; a manual inbox check may run already authorized autosend.

DirectMailAmerica MCP tools, authentication requirements and charge behavior
Tool and purposeAuthenticationCharge behavior
get_connection_status

Verify this MCP connection without charge or mailing. Public callers see anonymous access only. Authenticated callers see the workspace name, account owner, production/staging environment, granted OAuth scopes and each tool permission. Never returns credentials. Browser sign-in alone does not connect MCP.

Public; account details require authenticationNo charge; does not send
send_letter

Send a standard First-Class letter, Certified Mail, or black-and-white Express postcard. This can immediately spend credits and mail; it is not a preview. Guest x402 or Bearer workspace credits / x402. Optional couponCode; codes are validated server-side. PDF or plain text only. No general idempotency key: reconcile uncertain outcomes before retrying. Staging prevents postage, not payment or credit debits.

OptionalGuest x402, org credits, or pay-per-send
get_letter_status

No charge. Read stored job status and tracking by id with the owning workspace Bearer key. Does not itself poll the provider. Inspect the body for not_found.

OAuth or Bearer keyNo charge
list_jobs

No charge. List recent jobs in the authenticated workspace; default 20, maximum 100. MCP structuredContent returns {jobs:[...]}; the text content retains the JSON array for existing clients.

OAuth or Bearer keyNo charge
get_pricing

No charge. Public standard fixed-price quote from mailClass, pageCount and recipientCount; no artwork inspection or sending. Optional couponCode is validated server-side. Returns payment rails and live x402 assets.

NoneNo charge
get_credits

No charge. Read workspace prepaid balance in USD cents. Requires Bearer key.

OAuth or Bearer keyNo charge
purchase_credits

Buy credits with x402 USDC on Base/Solana. Requires Bearer key. Minimum 100 cents; default 1000. Retry a payment_required challenge with paymentSignature. Payments can be real even with a staging key.

OAuth or Bearer keyx402 USDC top-up
create_credit_checkout

Create a Square hosted Payment Link to fund credits. Never send PAN/CVV. Optional Bearer key: guest checkout creates a separate workspace and returns guestApiKey once. Credit packs minimum 100 cents; purpose=mailing minimum 1 cent. Does not send mail. Key environment does not select Square sandbox.

OptionalSquare Payment Link (no PAN)
get_payment_status

Check a Square checkout with paymentId and its workspace Bearer key. When paid, adds credits once; repeated status checks do not duplicate credits. Does not send mail.

OAuth or Bearer keyReads checkout; credits paid balance once
start_account_login

No charge. Return web login and Developers URLs only. Sign in with email magic link, password, Google or X; create an API key and configure Bearer auth separately. Does not authenticate MCP or automatically bind a browser session.

NoneNo charge
get_product_catalog

No charge. Public expanded product catalog: exact PDF dimensions, stocks and return envelopes. Products use provider cost +30%. Coupon books are excluded.

NoneNo charge
quote_product

Hold a 30-minute expanded-product quote using a workspace key, print-ready PDF and 1–100 US recipients. Uploads artwork to the provider in production; no charge or mailing. Each PDF page must match catalog dimensions; postcards require one landscape artwork page. Maximum 25 MiB. Staging quotes are demo estimates. Obtain approval of artwork, addresses and total before sending.

OAuth or Bearer keyQuote only; no charge
send_product_quote

With Bearer auth and confirmed=true, spend workspace credits and release the immutable saved quote. MCP accepts credits only for this tool; fund the workspace first. Reuse the same quote id after a timeout; retries never send it twice. authorizing / needs_review requires reconciliation, not a replacement order. Staging never mails.

OAuth or Bearer keyWorkspace credits; cost +30%
list_email_letterheads

No charge. Read saved letterhead presets, canvas designs, layout, versions and archive state in the owning workspace. Bearer key required; staging may read. No private storage paths, credits or postage.

OAuth or Bearer keyRead only; no charge
save_email_letterhead

No charge. Save a reusable letterhead or create its next immutable version. Production key required. Provide a 64-character lowercase hex id, version:0 for new or current version for editing, name, source:canvas with design.elements (text, line, rectangle), or source:pdf with pdfBase64 (unlocked one-page 8.5x11 unrotated US Letter, max 4 MB). PDF edits may omit pdfBase64 to retain their owned artwork. Layout top/bottom/left/right margins are inches; apply:first or all; ruling:none, solid or dashed; lineColor is hex. Canvas positions/sizes are PDF points from top left inside 18–594 x 18–774. Rules pin {id,version}; editing never updates existing rules or reviewed drafts. No postage or consent.

Production OAuth/keySaved stationery; no charge
archive_email_letterhead

No charge. Archive or restore an owned preset with {id,version,archived}. Production key required. Reversible; exact current version required. Archived presets cannot be newly assigned, but already pinned rules and drafts retain their artwork. No rule, history or postage changes.

Production OAuth/keyReversible archive; no charge
preview_email_letterhead

No charge. Render an unsaved canvas/PDF letterhead with {letterhead:save-input,sample:true,body?} as an embedded private PDF resource. sample:false returns blank stationery. Workspace key required; staging may preview. No saving, consent, pricing or mailing. Preview includes layout margins and ruling when sample:true.

OAuth or Bearer keySample PDF; no charge or saving
download_email_letterhead

No charge. Download an exact owned letterhead revision with {id,version} as an embedded private PDF resource. Workspace key required; staging may download. Archived versions remain accessible. No public URLs, postage or credits.

OAuth or Bearer keyPrivate PDF; no charge
download_email_letters

No charge. Download 1–50 owned emails as an embedded ZIP containing stored original EMLs, available PDFs and a manifest. Provide messages:[{id,version}] with exact current versions. Bearer key required; staging keys may download. Maximum 20 MB of documents. No mailbox changes, postage or credits. Pending deletions cannot be downloaded.

OAuth or Bearer keyZIP download; no charge
delete_email_letters

No charge. Permanently delete 1–50 owned emails from the workspace IMAP INBOX and Email history. Provide messages:[{id,version}] and confirmDelete:true only after explicit human approval of those emails. Requires a production key. Uses exact UIDs, matching UIDVALIDITY and UIDPLUS; never expunges unrelated messages. Formatting, submitting and uncertain mailings are protected. Failed deletions remain pending and cannot mail; retry the same selection after refreshing versions. Idempotent completed retries. Clears saved originals/unsent drafts; completed Jobs and mailing records remain. No postage or credit change.

Production OAuth/keyPermanent inbox deletion; no charge
preview_email_letter

No charge. Render a sample PDF from a mailing rule and optional sample body, without saving the rule, ingesting email, buying postage or changing credits. Workspace key required; staging keys may preview. Returns embedded PDF resource, pages and sample price. Supports rule.format header/address visibility, greeting, signature, reply cleanup, spacing, margins and page numbers. Actual emails are priced after formatting.

OAuth or Bearer keySample PDF; no charge or saving
get_email_to_letter

No charge. Read this workspace's generated inbox, ordered rules, budgets, usage, prepaid balance, address book, font catalog and polling cadence. Bearer key required; no inbox is created by reading.

OAuth or Bearer keyRead only; no charge
request_email_box

No charge. Generate the workspace's unique MailServiceNow inbox, or retry incomplete setup. Requires a production Bearer key. Repeated calls reuse the same address; one inbox per workspace. Returns activation state, never mailbox credentials. No email or letter is sent by this tool.

Production OAuth/keyInbox setup; no charge or mailing
check_email_box

Manually check only this workspace's existing inbox now, between scheduled runs. Production key required. Processes up to ten emails with the same matching, approval, authorized autosend, budget and duplicate safeguards as scheduled checks. Existing consented autosend can purchase postage; this tool grants no new consent. A shared worker lease prevents overlapping checks. Server enforces a 60-second cooldown per workspace, including failed attempts; retryAfterSeconds indicates when to retry. Respects admin and workspace pauses. Returns processed count, morePending, updated workspace and demo state; no mailbox credentials.

Production OAuth/keyMay run existing authorized autosend
update_email_letter_settings

Set the workspace enabled flag and per-letter/daily/monthly budgets in USD cents plus daily letter limit. Production key required. Enabling may resume previously authorized autosend; obtain approval for spending limits. No automatic card charges.

Production OAuth/keyControls existing autosend limits
save_email_letter_rule

Create or replace a mailing rule by id: exact sender/recipient, optional subject phrase, US return/destination addresses, approval or autosend, font, size and page limit. Optional letterhead:{id,version} pins a saved preset. Optional format controls printed fields, greeting, signature, reply cleanup, spacing/margins/page numbers. First enabled match wins; replacement keeps its position. Default approval, Times Roman 12 pt, 10 pages. Production key required. Autosend requires explicit human recurring-mailing authorization and consent=true; never infer consent. Changes apply to future emails.

Production OAuth/keyAutosend requires recurring-mailing consent
delete_email_letter_rule

No charge. Remove a mailing rule by id in the authenticated workspace. Production key required. Previously generated drafts remain in history; sent letters are unaffected.

Production OAuth/keyNo charge
list_email_letters

No charge. Read up to 50 emails and letter previews in the owning workspace, newest first. Pass the returned nextCursor as before to read older history. Bearer key required. Submitted means provider submission, not delivery.

OAuth or Bearer keyRead only; no charge
get_email_letter

No charge. Read an owned email's full printable text, rule snapshot, mailing state, version and quoted price. Bearer key required. Review its PDF with download_email_letter before approving. Uncertain submissions require support reconciliation; do not resend.

OAuth or Bearer keyRead only; no charge
download_email_letter

No charge. Return the private PDF preview/download or original EML as an embedded MCP resource with base64 blob, MIME type and filename. format defaults to pdf; eml includes original attachments. Requires the owning workspace key. No public URL or mailbox password is exposed; clients can decode and save the resource.

OAuth or Bearer keyRead only; no charge
edit_email_letter

No charge. Revise an owned draft's text, font, size, optional page limit and optional format settings and letterhead:{id,version} (or null to remove) using its current version. format controls printed fields, greeting/signature, reply cleanup, spacing/margins/page numbers; omitted format preserves the draft's settings. Production key required. Renders a new immutable PDF and increments version; always requires fresh review and approval. Cannot edit submitted, uncertain or rejected letters.

Production OAuth/keyPreview only; no charge
prepare_email_letter

No charge. Create an approval-required PDF draft from an owned unmatched email using id and exact version. By default uses the current enabled matching rule. Optionally provide mailing:{from,to,font,fontSize,maxPages,format,letterhead?} for a one-time destination without saving any automation rule. Defaults to Times Roman 12 pt. Requires a production key. Never buys postage, changes credits, enables autosend or records mailing/terms consent. Preview and explicitly approve separately with approve_email_letter. Refuses automatic replies, pending deletions, and previously prepared/submitted emails.

Production OAuth/keyApproval-required draft; no charge
reapply_email_letter

No charge. Rebuild an owned unsent draft using id, exact version and the latest enabled saved version of its associated rule. Retains edited letter text, applies updated addresses, font, formatting, page cap and pinned letterhead, recalculates price and increments version. Always forces approval mode and strips autosend consent; never buys postage, changes credits or dispatches. Production key required. Refuses submitted, uncertain, rejected, deletion-pending and one-time drafts without a saved rule. Optional ruleFingerprint guards an already-reviewed rule snapshot; concurrent rule/draft changes reject the update. Download and review the regenerated PDF and address before explicitly approving.

Production OAuth/keyUpdated approval-required preview; no charge
approve_email_letter

Approve printing and mailing of an owned preview using id, exact version, exact cents and confirmMail=true. Obtain explicit human approval of the PDF, addresses, total and Terms of Use first. Requires production key and prepaid credits; atomic budgets and duplicate protection apply. This can buy postage. Uncertain responses must be reconciled, never blindly retried.

Production OAuth/keyPrepaid credits; approved total
reject_email_letter

No charge. Reject an owned pending or blocked letter without mailing it. Production key required. Cannot cancel a submitted or uncertain mailing.

Production OAuth/keyNo charge
get_email_letter_polling

No charge. Read global Email to Letter polling settings and worker diagnostics. Requires a Bearer key owned by an administrator; ordinary workspace keys cannot read administrative diagnostics.

Administrator OAuth/keyRead only; no charge
update_email_letter_polling

Admin-only: enable/pause global polling or set intervalMinutes from 1 to 1440 (default 10). Production admin key required. Enabling may resume already authorized autosend across workspaces. Preserves active scheduler leases; does not invoke the worker immediately.

Production administrator OAuth/keyMay resume authorized autosend