Using the tools well
GoodPostal gives your AI assistant a set of tools for building emails, organizing contacts, and preparing campaigns. This page explains what those tools do, grouped by the job you are trying to get done, and how the safeguards keep you in control.
The full server exposes 53 tools and is what command line tools like Claude Code, Cursor, Codex, and the Gemini CLI connect to. Claude on the web and ChatGPT use a curated set of 44 tools: the same building and campaign tools, minus the account setup and delete actions, which stay in the GoodPostal dashboard where they belong.
Design and brand emails
Your assistant reads your brand and the component library, then assembles a template. Your logo and footer details are added to every template automatically from your workspace settings. Brand colors work differently: the assistant reads them with get_brand_guidelines and applies them as it designs, so emails stay on brand without you having to mention it.
| Name | Type | Required | Description |
|---|---|---|---|
get_brand_guidelines | Read | No | Load your brand colors, logo, and footer so designs match your identity. |
list_components / get_component | Read | No | Browse the component library by category and pull ready-made building blocks. |
get_showcase_example | Read | No | Load advanced layout patterns like cards and dark-mode sections. |
create_template / update_template | Write | No | Create a new email design or edit an existing one. Templates open in the visual editor afterward. |
list_templates / get_template | Read | No | Find your templates and read a specific design. |
send_test_email | Action | No | Send yourself a test to preview a template in a real inbox. |
upload_image / list_images / manage_image_folders | Write | No | Add images to a template and organize them into folders. |
update_email_branding / upload_email_logo | Write | No | Set your workspace brand colors, footer, and logo. |
Manage contacts
Find people, add them, and organize them into groups you can target with a campaign. Contact lookups return masked details; see the safeguards below.
| Name | Type | Required | Description |
|---|---|---|---|
search_contacts | Read | No | Find contacts by name, email, subscription status, or location (state, city, zip, country). |
create_contact / update_contact | Write | No | Add a new contact or update an existing one. |
list_contact_groups / create_contact_group | Read / Write | No | See your groups or create a new one for targeting. |
add_contacts_to_group | Write | No | Add matching contacts to a group in bulk, for example everyone in a given state, without listing them one by one. |
Launch campaigns
Build a campaign from a template, a sender, and an audience, then get a review link. The send itself always happens in the dashboard.
| Name | Type | Required | Description |
|---|---|---|---|
create_campaign / update_campaign | Write | No | Create a campaign draft linking a template, sender, and audience, or edit one. |
list_campaigns / get_campaign | Read | No | See your campaigns and read the details of one. |
review_and_send_campaign | Action | No | Check that a campaign is ready and return the dashboard review link. It never sends, schedules, or queues the campaign. |
manage_campaign_status | Write | No | Pause or resume a running campaign (full server only). |
Read analytics and account
| Name | Type | Required | Description |
|---|---|---|---|
get_campaign_analytics | Read | No | See how a campaign performed: delivered, opens, clicks, and more. |
get_workspace_info | Read | No | Read workspace details and your current plan. |
get_plan_usage | Read | No | Check your plan limits and current usage before a large operation. |
Set up sending (full server only)
Command line tools also get the setup tools for managing senders and configuring a tracking domain, and can list the sending services already connected. Connecting a new sending service (ESP) stays in the dashboard. The chat clients leave all of these to the dashboard.
| Name | Type | Required | Description |
|---|---|---|---|
list_email_providers | Read | No | See the email sending services connected to your workspace. |
list_sender_identities | Read | No | List sender identities with their verification status; only verified identities can send. Available in every client. |
create_sender_identity / update_sender_identity | Write | No | Add or update a sender identity. |
get_tracking_domain / set_tracking_domain / verify_tracking_domain | Read / Write | No | Read, set, and verify the custom tracking domain used for opens and clicks. |
Two safeguards, by design
A human approves every send
No tool can send, schedule, or queue a campaign. The closest tool, review_and_send_campaign, only checks readiness and returns a link to the campaign in your dashboard. You review the audience and content there and approve the send yourself. Campaigns are always created as drafts.
Contact details are masked
When the assistant searches contacts, it receives a privacy-safe display name (full first name plus last initial, such as "Chris D.") and a masked email (such as "da******47@gm**l.com"). Full last names, full email addresses, phone numbers, and street addresses are never returned to the assistant. Filters still run against the complete record, so targeting by location or subscription status works exactly as expected. This is a deliberate privacy feature.
How access works
GoodPostal uses OAuth 2.1. The consent screen asks you to sign in, pick which workspace to connect, and authorize. There are no per-permission checkboxes to tick: your AI tool decides what level of access to request, and authorizing grants what it asked for.
Two kinds of access exist behind that screen:
- Read access lets the assistant view templates, campaigns, contacts, and analytics.
- Write access lets it create and edit templates, contacts, and campaign drafts. Without it, changes are blocked and the assistant is told to re-authorize with write access.
Your own seat matters too. A viewer cannot make changes through an assistant no matter how the connection was authorized, and preparing a send requires that your account has permission to send in that workspace. Every token is scoped to the single workspace you chose, so the assistant can never reach another workspace's data.
Troubleshooting
| Name | Type | Required | Description |
|---|---|---|---|
Asked to sign in again | Auth | No | Your authorization expired. Re-authorize the connection. In Claude Code, run /mcp; in a chat client, remove and re-add the connector. |
Cannot make changes | Scope | No | The token grants read but not write access. Remove the connection and add it again so your AI tool requests write access afresh. If it still fails, check that your seat in the workspace is not a viewer. |
Workspace paused | Billing | No | A paused workspace (for example after a trial ends) blocks the connection entirely, including reads. Update your subscription in the dashboard, then reconnect. |
Too many requests | Rate limit | No | GoodPostal allows up to 60 MCP requests per minute. Wait a moment and retry if you hit the limit. |