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
- 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.
- 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. - 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-marketplaceThen 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.
| Tool and purpose | Authentication | Charge behavior |
|---|---|---|
get_connection_statusVerify 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 authentication | No charge; does not send |
send_letterSend 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. | Optional | Guest x402, org credits, or pay-per-send |
get_letter_statusNo 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 key | No charge |
list_jobsNo 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 key | No charge |
get_pricingNo 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. | None | No charge |
get_creditsNo charge. Read workspace prepaid balance in USD cents. Requires Bearer key. | OAuth or Bearer key | No charge |
purchase_creditsBuy 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 key | x402 USDC top-up |
create_credit_checkoutCreate 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. | Optional | Square Payment Link (no PAN) |
get_payment_statusCheck 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 key | Reads checkout; credits paid balance once |
start_account_loginNo 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. | None | No charge |
get_product_catalogNo charge. Public expanded product catalog: exact PDF dimensions, stocks and return envelopes. Products use provider cost +30%. Coupon books are excluded. | None | No charge |
quote_productHold 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 key | Quote only; no charge |
send_product_quoteWith 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 key | Workspace credits; cost +30% |
list_email_letterheadsNo 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 key | Read only; no charge |
save_email_letterheadNo 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/key | Saved stationery; no charge |
archive_email_letterheadNo 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/key | Reversible archive; no charge |
preview_email_letterheadNo 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 key | Sample PDF; no charge or saving |
download_email_letterheadNo 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 key | Private PDF; no charge |
download_email_lettersNo 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 key | ZIP download; no charge |
delete_email_lettersNo 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/key | Permanent inbox deletion; no charge |
preview_email_letterNo 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 key | Sample PDF; no charge or saving |
get_email_to_letterNo 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 key | Read only; no charge |
request_email_boxNo 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/key | Inbox setup; no charge or mailing |
check_email_boxManually 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/key | May run existing authorized autosend |
update_email_letter_settingsSet 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/key | Controls existing autosend limits |
save_email_letter_ruleCreate 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/key | Autosend requires recurring-mailing consent |
delete_email_letter_ruleNo 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/key | No charge |
list_email_lettersNo 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 key | Read only; no charge |
get_email_letterNo 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 key | Read only; no charge |
download_email_letterNo 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 key | Read only; no charge |
edit_email_letterNo 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/key | Preview only; no charge |
prepare_email_letterNo 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/key | Approval-required draft; no charge |
reapply_email_letterNo 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/key | Updated approval-required preview; no charge |
approve_email_letterApprove 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/key | Prepaid credits; approved total |
reject_email_letterNo charge. Reject an owned pending or blocked letter without mailing it. Production key required. Cannot cancel a submitted or uncertain mailing. | Production OAuth/key | No charge |
get_email_letter_pollingNo 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/key | Read only; no charge |
update_email_letter_pollingAdmin-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/key | May resume authorized autosend |