GoodPostal

Create a template from design_json, duplicate_from, or clone a brand-recolored starter with from_showcase. Prefer design_json so the first call is the finished email; use from_showcase only when the user asks to clone that starter. Raw html_content is not accepted. Call get_showcase_example before your first create_template in a conversation and build from a showcase's styled blocks; blocks sent without styles get a plain default look. External image URLs in design_json are copied into the workspace image library where possible, up to 20 per call, and the saved template uses the stored copies; the response warnings list any image left at its original URL or removed as unsafe; `icon:<name>` tokens become stored icon images. scaffold_instance is the server-assembled alternative to design_json and is preferred the same way. Building from a scaffold_instance marks its design direction as chosen and expires the other directions offered with it.

create_template

Create a retina PNG strip for a wave, diagonal, torn, zigzag, or scallop container edge. Store the returned URL in data-transition-top-src or data-transition-bottom-src together with the matching shape@depth token. The strip is saved to the workspace image library, in a Transitions folder; an identical strip already in the library is reused instead of saved again.

create_transition_image

Use this when the user wants to give a contact custom field a friendly name and type, or to describe a key their website already sends. Calling it again for the same key updates the existing definition. This only describes the key; it never changes any contact data and never restricts what the API accepts.

define_custom_field

Use this when the user wants to delete a folder from their image library. It deletes the folder; the images inside are not deleted and move to uncategorized. It needs an owner or admin role. The first call changes nothing and returns a confirmation request with the number of images that will move; the folder is deleted only when you call again with confirm: true. Do not use to take images out of a folder you want to keep (use move_images_to_folder), to create a folder (use create_image_folder), or to change the folder order (use reorder_image_folders).

delete_image_folder

Use this when the user wants to take people out of a smart group without changing its rules. It records an exclusion for each contact in contact_ids, so they stop counting as members even while the rules still match them; the contacts themselves are not changed or deleted. It takes effect on the first call, with no confirmation step. Do not use on a list group (use remove_contacts_from_group), to put an excluded person back (use include_contacts_in_smart_group), or to change who the rules select (use update_contact_group).

exclude_contacts_from_smart_group

Use this when the user shares a page (an article, blog post, event page, product page) to read or make an email about. Fetches the page and returns its text, its images, and any video embeds with a thumbnail, so you can import the images and add the video without relying on your own browsing. Use analyze_brand_from_url instead when the email should look like that site's brand. The result is complete after one call; do not fetch the same URL again in the same reply. This tool only reads pages. Use import_image to save any returned image URL to the workspace library.

fetch_webpage

Use only when the user asks what GoodPostal can do or wants the full reference (block types, merge tags, workflows). Never call just because a conversation started, and do not call for a direct email-creation request. Returns the complete reference guide with all available tools, workflows, and best practices.

get_app_guide

Use this when you need the workspace brand colors, logo URL, fonts, social links, or footer info before designing a template or setting up branding.

get_brand_guidelines

Use this when the user wants to view the full setup and details of a campaign including its template, sender, contact groups, readiness to send, and headline delivery stats (sent, delivered, opens, clicks, bounces, unsubscribes, complaints, open rate, click rate). Engagement numbers follow the contract described in get_campaign_analytics. Do not use for a full performance breakdown with top links or A/B variant results (use get_campaign_analytics) or to send the campaign (use prepare_campaign_review).

get_campaign

Use this when the user asks how a campaign performed: its open, click, bounce, unsubscribe, and complaint numbers and rates (including unique vs total opens/clicks), which links got the most clicks, or which A/B variant won and whether the result is statistically significant. Returns aggregate metrics only, never per-recipient data. When engagement.classification is "classified", open_count and click_count are people whose activity GoodPostal could stand behind. engagement.opens also carries privacy (Apple Mail auto-downloads), automated (bots), unverified, and raw (every request). Report the people figures as opened and clicked and name the other buckets by those words; raw is never a count of people. Do not use to check whether a campaign is ready to send or to view its setup (use get_campaign for that), and do not expect data before a campaign has started sending.

get_campaign_analytics

Use this when the user asks for the link to a campaign they already sent, so they can share it on social media or anywhere else. Returns the shareable address when the issue is already public, the address of the workspace archive that lists every public issue, and a message saying what to do next when it is not public yet. The public page shows the email itself with no tracking and no personal data in it, so the link is safe to share with anyone. Use publish_campaign_archive to make an issue public or take it back down.

get_campaign_public_link

Use this when you need the full block data for one specific pre-built component to drop into a template. Returns blocks with fresh IDs ready to use in design_json.blocks. Components are reusable building blocks; combine them with your own custom containers, columns, and blocks to compose professional emails. Do not use to browse the library (use list_components).

get_component

Use this when the user wants to put a signup form on their website, or asks how to connect a form they already have. Use list_subscription_forms to find the form_id. Pick the kind that fits the site. "widget" (the default) is one script tag that draws the form and handles the submission, and is the right answer for most people. "simple" is a plain HTML form with class names to style yourself. "styled" is the same form with the colors and spacing already inline. "headless" is for a site that already has its own form or checkbox (for example a newsletter opt-in on an order page): the site posts name and email to GoodPostal's endpoint and GoodPostal applies the form's opt-in mode, groups, and confirmation email. A form that makes visitors pass a bot check only works as the widget, which runs the check; the other three kinds are refused for such a form because anything submitted through them is rejected. The code is safe to hand to the user as is. Do not rewrite the endpoint URLs or the hidden form id in it. Getting the code also brings the form's embed signing key in line with its allowed websites: it creates a key when the form is limited to certain websites and has none, and deletes the key when the form is no longer limited.

get_form_embed_code

Use this to study complete, annotated email examples built with GoodPostal's block system. For initial email creation call it once without an ID with the category matching the email's intent, then once more with the single closest showcase_id to load its full annotated blocks; do not call again unless the user asks to compare alternatives. Study the composition quality, container nesting, rhythm, and mechanics, then diverge in content, palette, and section details for the user's actual request. For freeform designs, the catalog response includes a server-assigned design_brief to follow unless the user supplied explicit style direction. The examples use fictional demo content. The catalog also lists scaffold compositions. Compare saved offers with choose_design_direction, then select one with select_design_scaffold using its showcase_id and design_contract_id. This retrieval never chooses or expires an offer.

get_showcase_example

Use this when the user wants the full setup of one signup form: the inputs it collects, the groups subscribers join, its opt-in mode and confirmation email wording, and its bot protection. Use list_subscription_forms first to find the form_id. Do not use this to get the code for a website (use get_form_embed_code).

get_subscription_form

Use this when the user wants to view, edit, or copy a specific template. Returns the template design JSON (blocks + settings) plus a dashboard URL to view or edit it. The rendered email HTML is NOT returned inline (and cannot be shown in chat) — for a full visual preview, open the dashboard URL or send a test email. To show the user the template card, call show_template_card.

get_template

Use only when a block type or design_json shape you need is unknown; it is not a prerequisite for create_template and does not belong in the standard email-creation flow. Called without a topic it returns the compact core guide (schema, block types, children format, settings, footer/legal requirement). Pass a topic (dark_mode, containers, components, merge_tags) for deeper on-demand reference on that subject. Do not use to browse the component library itself (use list_components).

get_template_guide

Use only when the user explicitly asks about their workspace: contact count, template count, campaign count, email provider configuration, sender identities, and branding overview.

get_workspace_info

Use this when you have found a real image at a URL (e.g. from fetch_webpage, an article, or a product page) and want to use it in an email. Provide source_url — the server downloads, validates, and stores it in the image library, returning a hosted URL you can use as an image block src. Do NOT pass image bytes yourself. Do not use for external placeholder-image services (rejected) — use a real image or leave the block for the placeholder generator. Do not use for the workspace logo (use upload_email_logo).

import_image

Use this when the user wants a previously excluded contact to count in a smart group again. It deletes the saved exclusion, so the contact counts as a member again when it matches the group rules. It does not change opt-in or suppression status. Do not use for a list group (use add_contacts_to_group).

include_contacts_in_smart_group

Use this when the user wants to see their campaigns, check campaign status, or find a specific campaign. Each campaign carries open_rate and click_rate plus an engagement block. Engagement numbers follow the contract described in get_campaign_analytics.

list_campaigns

Use this when the user wants to browse the pre-built component library. Returns 90 curated components across 13 categories (heroes, headers, footers, content, features, CTAs, ecommerce, testimonials, stats, image galleries, pricing, surveys, engagement). Components are reusable building blocks; combine them with your own custom containers, columns, and blocks to compose emails. Do not use to fetch one component's block data (use get_component).

list_components

Use this when the user wants to see their contact groups, find a group for a campaign, or check group membership counts.

list_contact_groups

Use this when the user asks what extra contact facts their workspace tracks, wants to know what a custom field key means, or needs the exact payload to send contacts from their website or CRM. Returns every defined field plus keys seen on contacts that nobody has described yet.

list_custom_fields

Use this when the user wants to see their image library folders and how many images each one holds. Returns every folder with its UUID, name, slug, sort order, and image count. Do not use for browsing the images themselves (use list_images) or for changing folders (use create_image_folder, delete_image_folder, reorder_image_folders, or move_images_to_folder).

list_image_folders

Use this when the user wants to browse their uploaded images or find a specific image for a template.

list_images

Use this when the user wants to see their configured sender identities (from addresses) or find a sender for a campaign.

list_sender_identities

Use this when the user wants to see the signup forms that grow their contact list, check whether a form is live, or find a form to edit or embed. Call this before create_subscription_form so an existing form is reused rather than duplicated.

list_subscription_forms

Use this when the user wants to see their templates, find a specific template by name or status, or browse available templates for a campaign.

list_templates

Use this when the user wants to put images into a folder or take them out of every folder. It overwrites the folder of each image in image_ids with the destination folder_id, or moves them to uncategorized when folder_id is null. The image files themselves are not changed. Do not use to create a folder (use create_image_folder), to delete a folder (use delete_image_folder), or to browse images (use list_images).

move_images_to_folder

Use this to make targeted edits to an existing template without resending the whole design. Address blocks by their id (get_template returns design_json with block ids). Use only for a user-requested targeted edit to an existing template: change one block's content, styles, or attributes; insert, replace, or remove single blocks. For full redesigns use update_template. Draft and scheduled campaigns that use this template send its edited design. External image URLs in the patched design are copied into the workspace image library where possible, up to 20 per call, and the saved template uses the stored copies; the response warnings list any image left at its original URL or removed as unsafe; `icon:<name>` tokens become stored icon images.

patch_template

Draws the campaign review card and returns the dashboard review URL. Call it exactly once per reply, as your last tool call, after create_campaign and after every update_campaign edit in that reply are done. Never call it after each edit. Also use it when the user asks to send, schedule, or "go live" with a campaign; it checks readiness and hands the send to a person in the dashboard. It does NOT send the campaign, queue it, or schedule it — sending always requires explicit human approval in the dashboard. Share the returned review_url and tell the user to open it to approve and send. Do not use for editing a campaign (use update_campaign) or reading campaign details (use get_campaign).

prepare_campaign_review

Returns a rendered screenshot of the saved email, light only by default on ChatGPT; pass mode "both" for light and dark. Call it once after create_template to check what you built. If something is clearly wrong, fix it with one patch_template call. Do not preview and patch in a loop; the user refines in the dashboard.

preview_template

Use this when the user wants to share a campaign they already sent, or wants to take a shared one back down. Publishing puts the email on a public web page on the internet: anyone who has the address can open it without signing in, it is listed on the workspace archive page, and search engines can index it. The page shows the email itself with no tracking and no personal data in it. Pass public false to take the page down, which removes it from the web and keeps the address, so publishing again restores exactly the same link. Merge tags that name a person, such as first_name, need replacement text before an issue can go public; the refusal lists which keys are still missing so you can ask the user once and call again with fallbacks.

publish_campaign_archive

Use only when the user explicitly asks to permanently erase a custom field value from every contact in the workspace. Keeps the field definition. Requires an owner or admin. The first call changes nothing and requests confirmation; repeat with confirm: true to delete the values. More than 2,000 affected contacts are processed by a background job. Repeating a confirmed call can queue another purge and can erase values added since the earlier call. Use remove_custom_field_definition to remove only the definition.

purge_custom_field_data

Use this when the user wants to take specific contacts out of a list group. It removes each contact in contact_ids from the group; the contacts themselves are not deleted and stay in the workspace and in their other groups. The first call changes nothing and returns a confirmation request; the contacts are removed only when you call again with confirm: true. A smart group fills itself from its rules and refuses this tool. Do not use on a smart group (use exclude_contacts_from_smart_group) or to add contacts (use add_contacts_to_group).

remove_contacts_from_group

Use this when the user wants to remove a custom field definition. Deletes its label and type and removes the key from the engagement signal whitelist if present. Contacts keep their stored values and filters keep working. Use purge_custom_field_data separately to permanently erase the values across the workspace.

remove_custom_field_definition

Use this when the user wants to remove the workspace email logo, icon, or its dark-mode variant. Clears the saved asset URL and dimensions; keeps the stored file so earlier templates still work. Dark-mode rendering follows the current settings. Requires an owner or admin. The first call changes nothing and requests confirmation; repeat with confirm: true to remove it. Use upload_email_logo to upload or replace an asset.

remove_email_logo

Use this when the user wants to change the order of their image library folders. It overwrites the stored position of each folder in folder_ids with its place in that list, first to last; folders left out keep their current position. Folders and images are not otherwise changed. Do not use to create or delete a folder (use create_image_folder or delete_image_folder) or to move images between folders (use move_images_to_folder).

reorder_image_folders

Use this for LOCAL files only, when the image exists on the machine you are running on and has no public URL. If you have a URL, use upload_image with image_url instead. Returns a one-time signed URL; POST the file to it as multipart field file. The URL expires in 15 minutes and works exactly once.

request_image_upload