How to write, structure, and configure emails so Aampe’s agents can learn and personalize effectively.Documentation Index
Fetch the complete documentation index at: https://kb.aampe.com/llms.txt
Use this file to discover all available pages before exploring further.
Differences between existing email content vs Aampe email
Aampe’s content model is fundamentally different from what any generic email builder understands:Building a regular EmailTemplate → Add Content and Merge Tags → Send
Building a Aampe EmailTemplate → Fields → fill with Components × Labels × Alternates → Agent Learning Enabled 🤖
How Agents Learn from Emails
Aampe’s reinforcement learning agents don’t just send emails — they learn from every interaction. In this context, an interaction means the agent putting labeled content in front of a user, whether that’s through email, push, or an in-app surface. Opens, clicks, and similar behaviors are signals that help the agent learn from those interactions over time. As those signals accumulate, agents discover each user’s preferences across value propositions, tones, offerings, and calls to action, then use those preferences to assemble the most effective message for each person. For this to work, agents need material to experiment with. If every email says the same thing in the same way, there’s nothing to learn. The more varied and well-structured your email content is, the faster agents learn and the better your results.The Golden Rule: Coverage Over Volume
The single most important principle for agent learning is coverage, not message volume. Coverage means having content that spans the full range of things your users might care about. Think of it this way: agents don’t change user behavior — they discover it. If a user isn’t in the market to buy something right now, it doesn’t matter how many “buy now” emails you have. But if you also have content about new features, tips and tricks, community stories, or educational material, the agent can find something that resonates, keep the user engaged, and set the stage for conversion when the moment is right. Your Strategy Map defines all the things a user could be in-market for. You need at least some content for most of those rows, because that’s what allows agents to meet users where they are. What this means practically:- If your Content Map has 80 rows and you’ve implemented content for 10 of them, adding more alternates to those 10 won’t help nearly as much as covering 30–40 rows with even basic content.
- A customer with 200 messages concentrated on a single topic can still have 49% of users receiving nothing that resonates, because coverage was only 10% of the product.
- Even if you’re optimizing for a specific business outcome (like purchases), agents need diverse content to learn the indirect paths that lead to that outcome.
Structuring Email Content for Agents
Components: The Building Blocks
An email in Aampe is built from components — distinct sections of the email that agents can mix and match. Common email sections include:- Subject line — the first thing users see; high-impact for open rates
- Pre-header — the preview text shown alongside the subject line in the inbox
- Email title / headline — the main heading inside the email body
- Body text — the core message content
- Call to action (CTA) — the button or link driving the desired action
- Offering — the product, feature, or benefit being highlighted
Prioritize Value Proposition and Offering components over structural ones like Greeting and CTA. Agents learn the most from semantic components the what and why of your message rather than structural ones like
**"Hi {first-name}"** or “Click here.”Labels: What Agents Actually Learn On
Labels are the core of agent learning. They’re the categories that tell the agent what kind of content an alternate represents. When an agent learns that a user prefers “social proof” over “financial benefit” as a value proposition, it’s learning at the label level. Common label types include:- Value Proposition labels: Social Proof, Convenience, Savings, Reliability, Trust, Exclusivity
- Offering labels: Feature-specific labels tied to your product (e.g., “Group Ride,” “Document Manager,” “Mobile Pay”)
- Tone labels: Direct, Motivational, Reassuring, Enthusiastic, Encouraging
- CTA labels: Soft (Learn more), Direct (Buy now), Urgent (Don’t miss out)
- Use all available labels (or as many as possible) for every component in an email. If you have 6 value proposition labels, each email message should ideally have alternates for all 6, not just 2 or 3.
- Every label is a hypothesis. If a component has only one label, the agent can’t learn preferences for that component — there’s nothing to compare against.
- If a label has too few alternates, users who prefer that label won’t receive the message again because agents protect against redundant experiences.
Alternates: Giving Agents Options
Alternates are the different versions of copy within a component, tagged with labels. They’re what the agent actually selects from when assembling a message. The rule of thumb: aim for at least 3 alternates per label per component within each message group. Why 3? With fewer, agents don’t have enough variety to prevent repetitive experiences. With significantly more (say 10+ per label while another label has only 1), the imbalance can skew learning. Keep your alternates balanced across labels. Don’t create 10 alternates for one label and 1 for another — this creates uneven learning and means the agent over-indexes on the well-represented label.Email-Specific Best Practices
1. Keep Component Count Manageable
Emails are more complex than push notifications because they have more sections & opportunities for personalization. But more components means exponentially more combinations, and agents need enough interactions to learn patterns across all of them. Recommended approach:- Aim for 3 to 5 components per email message. This is the sweet spot for meaningful learning.
- If your email has many sections (e.g., header, intro, 3 product blocks, footer), consider which sections truly benefit from personalization and which can stay static.
- Each label is a hypothesis, and each message is an experiment. The more complex the experiment, the higher the chance agents measure noise instead of signal.
2. Use Component Locking
When your email has repeating sections (e.g., three product recommendation blocks), use label locking to ensure label consistency across them. Without locking, agents might pair a “luxury” focused headline with a “budget savings” body copy creating a disjointed experience. Component locking ensures that when the agent selects a label for one section, matching sections use the same label, keeping the email coherent.3. Make Subject Lines and Pre-headers Dynamic
Subject lines and pre-headers are the highest-impact components of an email because they determine whether the email gets opened at all. Make both dynamic with labeled alternates so agents can learn what drives opens for different users.- Create subject line alternates that vary by value proposition and tone.
- Pair pre-headers with subject lines thoughtfully, they should complement, not repeat.
4. Preserve Your Template’s Technical Elements
When importing HTML templates, make sure to preserve:- Tracking parameters on all URLs (UTM tags, session IDs)
- Conditional logic from your ESP (Braze liquid tags, Customer.io conditionals)
- Content blocks (footers, unsubscribe links, compliance text)
- Image query strings (cache-busting parameters, resize specifications)
5. Handle ESP Variables Separately
Your email templates likely contain variables from your ESP (like{{first_name}}, Braze connected content, or unsubscribe links). These are not Aampe variables — they’re resolved by your send tool at delivery time.
When configuring your template, distinguish between:
- Aampe fields — sections where the agent selects personalized content (your components)
- ESP/personalization fields — variables resolved by your send tool (first name, unsubscribe links, dynamic content from APIs)
Note: If you plan to use your ESP’s conditional logic, such as Braze Liquid tags or Customer.io conditionals, please inform your Customer Success Manager so we can enable the appropriate support on our end.
6. Working with Modular Email Layouts
Many teams don’t work from a single fixed email template. They have a set of reusable HTML blocks — headers, body sections, CTAs — that get mixed and matched into different layouts depending on the campaign. This is compatible with Aampe; here’s how to approach it. Set up one template per distinct layout, not one per every possible combination. If you have 3 common email structures (say, a single-column with a hero, a two-block product layout, and a plain text format), configure those 3 as separate templates in Composer. Avoid trying to capture every permutation — that creates more complexity than agents can meaningfully learn from. ESP content blocks stay as-is. If your modular blocks are managed by your ESP (for example, Braze content blocks referenced as liquid tags), you don’t need to change anything. Aampe preserves those references in the HTML and your ESP resolves them at send time. What Aampe personalizes are the text and content fields within the template, not the structural blocks themselves. If you want agents to learn which layout works better, make it a component. If the structural variation is meaningful — like testing a hero image layout vs. a plain text layout — you can create a label for it (e.g. an “Email Format” component with labels like “Hero” and “Plain”). This lets agents discover which layout resonates with each user over time.One heads-up: Making a header section dynamic can sometimes strip its CSS styling in some email clients. If you see rendering issues after configuring a header as a variable, check that the styling is still applied and add it back manually if needed.
Understanding your Content Coverage
Content Coverage (found under Monitoring > Label Management) is your primary tool for identifying where to invest your content efforts. It shows a grid comparing two component types (e.g., Offering × Value Proposition) and reveals:- Gaps (black triangle): label pairs with fewer than 3 alternates — these need more content
- Opportunities (yellow triangle): label pairs that appear in a message group but are missing one label — easy wins for expansion
- Blank cells: label pairs that haven’t appeared together yet — new territory to explore
Content Creation Targets
While every account is different, here are general benchmarks based on experience across customers: For a healthy email strategy:- Cover 50–60% of your Content Map rows within the first year
- Aim for at least 3 alternates per label per component in each message group
- Target 10+ offering labels, 10+ value proposition labels, and 5+ CTA labels for mature programs
- Ensure content spans both core value propositions (the main drivers of your business) and niche value propositions (contextual, specific angles)
- Agents need enough interactions to discover preferences. A healthy baseline is 14+ agent-customer interactions per week per user (the TACIR metric), with the ideal range being 28–42.
- This doesn’t mean sending 14 emails per week — it means having enough content variety across channels (push, email, surfaces) so agents have material to work with at every touchpoint.
- More content variety, not more sends, is what drives higher interaction rates.
Common Aampe Email Mistakes to Avoid
Building content for only one goal. If you define a single outcome and build all content narrowly around it, learning stalls. Agents can’t explore alternative paths to conversion, and users get over-messaged on a single topic. Remember: measurement should be scoped to a goal, but learning shouldn’t be. Too many components in one email. A single email with 21 components can generate trillions of alternate combinations, but agents can’t meaningfully learn across that many variables. Keep it focused. If you want to start simple, begin with subject lines and pre-headers. Unbalanced label coverage. Having 10 alternates for one label and 1 for another creates skewed learning. Keep alternate counts roughly even across labels. Treating structural components as semantic ones. Greeting variations (“Hi!” vs “Hey!” vs “Hello!”) don’t teach agents much about user preferences. Treat greetings as openers or hooks to engage the customer. They do not necessarily have to be a simple hello — they can also be a statement or a question. Invest your effort in meaningful content variation — the value propositions, offerings, and angles that actually differentiate messages. Never iterating on content. Once you’ve established a healthy baseline, review performance regularly, refresh stale content, and add new variants where you need more coverage or experimentation. This iterative process is what turns a good portfolio into a great one.Quick Reference Checklist
- Content Map covers the full range of user motivations, not just one goal
- 50%+ of Content Map rows have at least basic content implemented
- Each email message has 3–6 dynamic components
- Every component uses all available labels (or as many as make sense)
- At least 3 alternates per label per component
- Alternate counts are balanced across labels
- Subject lines and pre-headers are dynamic with labeled alternates
- Component locking is enabled for repeating sections
- Value proposition and offering components are prioritized over greetings/CTAs
- Content Coverage map is reviewed regularly for gaps and opportunities
- Template technical elements (tracking, conditional logic, content blocks) are preserved