# Poplar MCP > Poplar connects your AI agent directly to programmatic direct mail services. This server lets you trigger physical mailers—postcards or letters—by providing a campaign ID and recipient details in plain language. You can standardize US addresses before mailing, manage entire audience lists (adding members or applying suppression flags), and track the whole workflow from list prep to final delivery status. It handles all your high-touch physical outreach directly through conversation. ## Overview - **Category:** marketing-automation - **Price:** Free - **Tags:** direct-mail, programmatic-marketing, address-verification, physical-outreach, campaign-tracking, automation ## Description **Poplar** hooks your AI agent right into programmatic direct mail services. This isn't some basic API wrapper; it lets you trigger *actual* physical campaigns—postcards or letters—by talking to the system in plain language. You use this server when you need to manage high-touch, real-world outreach without lifting a finger. To get started, your agent first runs `get_api_profile` after authentication; that just verifies your Poplar account details. Then, it gets down to business by making sure your list and addresses are solid before any physical mail goes out. If you're dealing with raw address fields—like a street name or city—your agent uses `standardize_us_address` to clean up the data. This function verifies the US mailing format, giving you USPS-compliant results that guarantee high deliverability rates for your campaign. When it comes to building your target list, you have full control over who sees your mail. Your agent can pull a complete roster of all existing audience groups using `list_audiences`. You'll need to add new people by running `add_to_audience`, or if someone shouldn't get physical mail ever again, it hits the global 'Do Not Mail' list with `add_to_suppression_list`. Once your list is prepped and validated, you execute the campaign. To send out actual physical pieces, your agent runs `trigger_physical_mailer`, which requires just a campaign ID and recipient data to fire off postcards or letters through Poplar's system. You can also check what creative materials are available by pulling a list using `list_mail_creatives`. Monitoring the run is easy. To see if production started, or where the mailers stand in delivery, your agent checks the status with `get_mailer_status`, referencing a specific campaign ID. You can also pull up every active direct mail effort by calling `list_marketing_campaigns` and get an overview of your account’s finances using `list_billing_history`. Finally, you close the loop on revenue tracking. When a customer places a physical order related to your mailing campaign, your agent sends those transaction details back into Poplar using `report_transaction`, letting you directly connect the cost of the mailer to measurable return on investment. ## Tools ### add_to_audience Adds a specified recipient to an existing mailing audience list in your account. ### add_to_suppression_list Places a recipient on the global 'Do Not Mail' list, preventing them from receiving future physical mailers. ### get_api_profile Retrieves basic information about your Poplar account after authentication. ### get_mailer_status Checks the current production and delivery status for a specific physical mailer campaign ID. ### list_audiences Lists all mailing audiences you have set up in your Poplar account. ### list_billing_history Provides a summary of your account's billing and invoice data. ### list_marketing_campaigns Lists every direct mail campaign ID currently active in your account. ### list_mail_creatives Retrieves a list of all physical mailer designs or templates you have uploaded to Poplar. ### standardize_us_address Cleans and verifies a US mailing address, returning the correct format for high deliverability. ### report_transaction Sends a customer order's transaction details back to Poplar so you can track its return on investment (ROI). ### trigger_physical_mailer Sends out actual physical mail (postcard or letter) when provided with a campaign ID and recipient details. ## Prompt Examples **Prompt:** ``` Send a postcard to Jane Doe using campaign ID 'camp_123'. ``` **Response:** ``` I've started the process for campaign camp_123. To trigger the mailer, I need Jane Doe's full mailing address (street, city, state, zip). Once provided, I'll send the request to Poplar. Should I also include any custom merge tags? ``` **Prompt:** ``` Standardize this address: 123 main st, nyc, ny 10001. ``` **Response:** ``` Standardizing... Poplar has verified the address. The correct USPS format is: '123 MAIN ST, NEW YORK, NY 10001-4107'. The address is valid and deliverable. Would you like to add this recipient to an audience list? ``` **Prompt:** ``` List all active audiences and find 'Holiday VIPs'. ``` **Response:** ``` Retrieving audiences... I found 4 groups in your account, including 'Holiday VIPs' (ID: aud_552) with 1,200 members. Other audiences are 'New Signups', 'Churn Risks', and 'Global Suppressions'. Should I list the members of 'Holiday VIPs'? ``` ## Capabilities ### Standardize US Addresses Takes raw address fields (like street and city) and returns a verified, USPS-compliant format for guaranteed deliverability. ### Execute Physical Mailers Uses a campaign ID and recipient data to send physical mail pieces—postcards or letters—through Poplar's system. ### Build and Manage Mailing Lists Allows you to list all existing audiences, add new members by email/address, or apply a global 'Do Not Mail' flag using `add_to_audience` or `add_to_suppression_list`. ### Check Campaign Status Retrieves real-time data on a specific mailer run, showing its production and delivery status via `get_mailer_status`. ### Attribute Sales Data Sends customer order details back into Poplar using `report_transaction`, connecting physical mailing costs to measurable revenue. ## Use Cases ### The Win-Back Campaign A retention manager needs to send a postcard to customers inactive for six months. They ask their agent: 'Find all users in the 'Lapsed' audience and trigger a win-back mailer.' The agent first runs `list_audiences` to confirm the group, then uses `trigger_physical_mailer`, completing the outreach without manual steps. ### The Dirty Data Cleanup An e-commerce owner gets a list of 500 addresses copied from an old source. They ask their agent to validate it. The agent calls `standardize_us_address` on each record, cleaning up state abbreviations and zip codes, making the entire batch ready for mailing. ### Tracking Campaign Success A growth marketer runs a high-value mailer campaign. Later, they receive sales data for those recipients. They tell their agent to report the orders back using `report_transaction`. This action closes the loop by linking physical spend to measurable profit. ### Compliance and Opt-Outs The marketing team needs to respect new compliance rules. Instead of manually updating lists, they instruct their agent to run `add_to_suppression_list` for any user who calls customer service and requests opt-out status. ## Benefits - **Stop Guessing on Addresses:** Use `standardize_us_address` to guarantee every mailing address is in USPS-compliant format. This isn't just cleaning; it’s making the mail physically deliverable, reducing bounce rates. - **Manage Lists Without Spreadsheets:** You don't need CSV uploads for list maintenance. The AI agent handles adding users (`add_to_audience`) or opting people out (`add_to_suppression_list`) directly from conversation. - **Full Campaign Visibility:** Easily check the status of mailers using `get_mailer_status` and review all available designs with `list_mail_creatives`. You see exactly where every campaign stands. - **Close the Loop on ROI:** Don't just send mail—track it. Run `report_transaction` to pipe sale data back into Poplar, finally connecting your physical marketing costs to actual revenue numbers. - **Control Your Audience Flow:** Use `list_audiences` and `add_to_audience` together to segment leads based on criteria (e.g., 'VIPs who haven't bought in 90 days') before triggering the mailer. ## How It Works The bottom line is: your AI client handles the entire physical marketing pipeline—from dirty addresses to printed mailer tracking—without you having to run multiple API calls manually. 1. First, you connect your AI client and supply the Poplar Access Token. 2. Next, your agent runs a sequence of tools—for example, first calling `standardize_us_address` on raw data, then using `add_to_audience` to build the final list. 3. Finally, the agent executes `trigger_physical_mailer`, sending the validated mailing data to Poplar for deployment. ## Frequently Asked Questions **How do I get my Poplar Access Token?** Log in to your Poplar account and navigate to the **API Settings** or **Developer** section. You will find your Access Token there. Use a Test Token for development and a Production Token for live mailings. **Can I standardize non-US addresses?** No, Poplar's address standardization service is specifically designed for US addresses only. For international mailing, ensure your addresses are pre-formatted correctly. **How can I check if a mailer has been delivered?** Use the `get_mailer_status` tool with the unique mailer ID. It will return the current status, including production phases and the final USPS delivery confirmation when available. **Is the integration secure for customer addresses?** Absolutely. The integration uses official Poplar Bearer tokens over HTTPS. Your credentials and customer data are encrypted and stored securely within the Vinkius Cloud infrastructure. **How do I use the `list_billing_history` tool with Poplar?** You can view your account's complete spending details. The tool pulls all invoice data and billing records directly from your Poplar dashboard, helping you track usage across different campaigns. **If I use `standardize_us_address`, what happens when my input address format is incorrect?** The function returns a structured error detailing exactly why the USPS validation failed. It won't process invalid addresses, allowing your agent to correct the source data before retrying. **How does using the `add_to_suppression_list` tool ensure I manage opt-outs correctly?** It immediately adds recipients to Poplar's global 'Do Not Mail' list. This action prevents any future physical mailer from targeting that specific individual, ensuring compliance. **Are there rate limits when I use `trigger_physical_mailer`?** Poplar manages standard API rate limits to ensure stability across all users. The server handles throttling if you exceed established thresholds, automatically pausing and retrying the request.