How AI Agents Write and Edit Emails in Mailpuff

An AI agent writes a Mailpuff email as a list of simple blocks, sent as JSON to the create-campaign or set-campaign-content tool. There are eight block types: heading, paragraph, list, quote, button, image, divider and spacer. Mailpuff turns them into the email editor’s own blocks and into the HTML that gets sent, so the owner can open the draft and finish it by hand like any other email.

What does a campaign look like in blocks?

Here is a complete create-campaign call. Only subject is required. Without an audience, the campaign goes to everyone subscribed, and the sender comes from Mailpuff’s settings.

{
  "subject": "Our spring sale starts Monday",
  "preheader": "Three days, 20% off everything in the shop.",
  "audience_type": "tag",
  "audience_id": 4,
  "theme": "gazette",
  "blocks": [
    { "type": "heading", "text": "Spring sale, three days only", "level": 1 },
    { "type": "paragraph", "text": "Hi {{first_name}},nfrom Monday to Wednesday everything is **20% off**." },
    { "type": "list", "items": ["Free shipping over $50", "No code needed", "Ends Wednesday at midnight"] },
    { "type": "button", "text": "Shop the sale", "url": "https://example.com/shop", "align": "center" },
    { "type": "divider" },
    { "type": "paragraph", "text": "Questions? Just reply to this email.", "align": "center" }
  ]
}

The answer has the new campaign’s id, its status (draft), a review_url where the owner reviews and sends it, and an editor_url that opens it in the editor. Nothing is sent.

Which block types can an agent use?

Type	Fields	Notes
heading	text, level (1, 2 or 3), align	Level defaults to 2. Text is required.
paragraph	text, align	Use n for a line break.
list	items (array of strings), ordered	Set ordered to true for a numbered list.
quote	text
button	text, url, align, color, text_color	Without a color, the button takes the theme’s link color, and the text color is picked to stay readable.
image	src, alt, href, width, align	src must be an http or https URL. Width runs from 20 to 600 pixels.
divider	None	A thin line.
spacer	height	4 to 120 pixels, 20 by default.

align is left, center or right. Colors are written as #RRGGBB. One body takes up to 200 blocks, and one block up to 5,000 characters.

How do I format text inside a block?

Text uses a small part of Markdown. Anything else is kept as plain text.

• **bold** for bold
• *italic* for italic
• [link text](https://example.com) for a link
• n for a line break inside a paragraph

Merge tags such as {{first_name}} pass through and are filled in for each reader at send time. A link or a button can point at a merge tag, for example "url": "{{manage_subscription_url}}".

Which merge tags work in Mailpuff?

Merge tag	Becomes
{{first_name}}, {{last_name}}, {{full_name}}	The reader’s name
{{email}}	The reader’s email address
{{business_name}}, {{business_address}}	Your business name and postal address from Settings
{{site_name}}, {{site_url}}	Your site’s name and address
{{unsubscribe_url}}	The reader’s unsubscribe link
{{manage_subscription_url}}	The reader’s preferences page
{{date}}	Today’s date in your site’s date format
{{last_post_title}}, {{last_post_url}}	Your latest blog post
{{confirm_url}}	The confirm link, in the confirmation email only

Every campaign gets the unsubscribe footer and your postal address on its own, so the agent doesn’t need to add them.

How does an agent change part of an existing email?

To change one part, the agent reads the campaign with get-campaign, edits that one block in the blocks array, and sends the whole array back with set-campaign-content. That call replaces the entire body, including anything the owner changed in the editor since it was read. So the agent should read first, change only what the owner asked for, and write straight after.

Check blocks_exact in the get-campaign answer before you edit:

• true: the blocks match the email exactly. Edit and send them back.
• false: the email has parts with no block type, such as social links, a menu, a video, raw HTML, MJML, underline, strikethrough or colored text. The blocks are an approximation, and writing them back would drop those parts. Change this email in the editor instead.

To change the subject, preview text, sender or audience, use update-campaign. It never touches the body.

How do email themes and styles work?

A theme sets the font, text sizes, colors, backgrounds and corner radius in one go. Mailpuff ships eight: clean, gazette, charcoal, sage, ember, typewriter, poster and pebble. list-email-themes returns each one with the exact styles it sets. Every theme keeps text readable on its background.

Pass theme to create-campaign, or change the look of a draft with set-campaign-style. That tool takes a theme, single styles on top of it, or both:

{
  "campaign_id": 42,
  "theme": "sage",
  "styles": {
    "font": "georgia",
    "fontSize": 17,
    "linkColor": "#2F6B4F",
    "borderRadius": 12
  }
}

Style	Accepted values
font	system, helvetica, arial, verdana, trebuchet, georgia, palatino, times, mono, courier
fontSize	12 to 20
h1Size, h2Size, h3Size	12 to 60
lineHeight	1 to 2.2
textColor, headingColor, linkColor	#RRGGBB
outerBg, bgColor	#RRGGBB for the page and the content area
borderRadius	0 to 24
linkUnderline	true or false

set-campaign-style never changes the words. An email with parts only the editor can draw, such as social links or raw HTML, is restyled in the editor, and the tool’s answer says so.

Can an agent send HTML or MJML instead?

An agent can pass content_html instead of blocks. Mailpuff removes scripts and unsafe markup. Blocks are the better choice, because the editor opens them as headings, paragraphs, buttons and images the owner can change one by one.

MJML is written in the editor itself: type /mjml to add an MJML block, or choose “Edit as MJML” from the editor menu. The tools don’t take MJML.

What should an agent do after writing the email?

1. Send a test with send-campaign-test and ask the owner to read it, ideally on a phone.
2. Run check-send-readiness with the campaign id. It checks preview text, a subject of 60 characters or fewer, Gmail’s 102 KB clipping size and link shorteners, among other things.
3. Share the review_url so the owner can look before anything goes out.

Sending is covered in AI agent permissions and safe sending.

FAQ

Can an agent add images from my media library?

Yes, with the image’s full URL in src. Any public http or https image works. Add alt text for readers whose email app blocks images.

Why did my button come out in a different color?

A button without color takes the theme’s link color, so it matches the email. Set color and text_color to pick your own.

Does the agent’s draft look the same in the editor?

Yes. Each block becomes the editor’s own block of the same kind, so the owner sees the same email and can change any part of it.

Related guides

• Mailpuff MCP tools reference
• AI agent permissions and safe sending
• Connect an AI agent to Mailpuff with MCP