wiki/content/blog/how-to-use-agentmail.md

title, description, date, slug, published, featured, featuredOrder, blogFeatured, image, tags

title	description	date	slug	published	featured	featuredOrder	blogFeatured	image	tags
How to use AgentMail with Markdown Sync	Complete guide to setting up AgentMail for newsletters and contact forms in your markdown blog	2025-12-27	how-to-use-agentmail	true	true	3	true	/images/agentmail-blog.png	agentmail newsletter email setup

AgentMail provides email infrastructure for your markdown blog, enabling newsletter subscriptions, contact forms, and automated email notifications. This guide covers setup, configuration, and usage.

What is AgentMail

AgentMail is an email service designed for AI agents and developers. It handles email sending and receiving without OAuth or MFA requirements, making it ideal for automated workflows.

For this markdown blog framework, AgentMail powers:

• Newsletter subscriptions and sending
• Contact forms on posts and pages
• Developer notifications for new subscribers
• Weekly digest emails
• Weekly stats summaries

Setup

1. Create an AgentMail account

Sign up at agentmail.to and create an inbox. Your inbox address will look like yourname@agentmail.to.

2. Get your API key

In the AgentMail dashboard, navigate to API settings and copy your API key. You'll need this for Convex environment variables.

3. Configure Convex environment variables

In your Convex dashboard, go to Settings > Environment Variables and add:

Variable	Description	Required
AGENTMAIL_API_KEY	Your AgentMail API key	Yes
AGENTMAIL_INBOX	Your inbox address (e.g., markdown@agentmail.to)	Yes
AGENTMAIL_CONTACT_EMAIL	Contact form recipient (defaults to inbox if not set)	No

Important: Never hardcode email addresses in your code. Always use environment variables.

4. Enable features in siteConfig

Edit src/config/siteConfig.ts to enable newsletter and contact form features:

newsletter: {
  enabled: true,
  showOnHomepage: true,
  showOnBlogPage: true,
  showOnPosts: true,
  title: "Subscribe to the newsletter",
  description: "Get updates delivered to your inbox",
},

contactForm: {
  enabled: true,
  title: "Get in touch",
  description: "Send us a message",
},

Newsletter features

Subscriber management

The Newsletter Admin page at /newsletter-admin provides:

• View all subscribers with search and filters
• Delete subscribers
• Send blog posts as newsletters
• Write and send custom emails with markdown support
• View email statistics dashboard
• Track recent sends (last 10)

Sending newsletters

Via CLI:

# Send a specific post to all subscribers
npm run newsletter:send setup-guide

# Send weekly stats summary to your inbox
npm run newsletter:send:stats

Via Admin UI:

1. Navigate to /newsletter-admin
2. Select "Send Post" or "Write Email" from the sidebar
3. Choose a post or compose a custom email
4. Click "Send Newsletter"

Weekly digest

Automated weekly digest emails are sent every Sunday at 9:00 AM UTC. They include all posts published in the last 7 days.

Configure in siteConfig.ts:

weeklyDigest: {
  enabled: true,
},

Developer notifications

Receive email notifications when:

• A new subscriber signs up
• Weekly stats summary (every Monday at 9:00 AM UTC)

Configure in siteConfig.ts:

newsletterNotifications: {
  enabled: true,
},

Notifications are sent to AGENTMAIL_CONTACT_EMAIL or AGENTMAIL_INBOX if contact email is not set.

Contact forms

Enable on posts and pages

Add contactForm: true to any post or page frontmatter:

---
title: "Contact Us"
slug: "contact"
published: true
contactForm: true
---

Your page content here...

The contact form includes:

• Name field
• Email field
• Message field

Submissions are stored in Convex and sent via AgentMail to your configured recipient.

Frontmatter options

Field	Type	Description
contactForm	boolean	Enable contact form on this post/page

Frontmatter options

Newsletter signup

Control newsletter signup display per post/page:

---
title: "My Post"
newsletter: true # Show signup (default: follows siteConfig)
---

Or hide it:

---
title: "My Post"
newsletter: false # Hide signup even if enabled globally
---

Environment variables

All AgentMail features require these Convex environment variables:

Required:

• AGENTMAIL_API_KEY - Your AgentMail API key
• AGENTMAIL_INBOX - Your inbox address

Optional:

• AGENTMAIL_CONTACT_EMAIL - Contact form recipient (defaults to inbox)

Note: If environment variables are not configured, users will see: "AgentMail Environment Variables are not configured in production. Please set AGENTMAIL_API_KEY and AGENTMAIL_INBOX."

CLI commands

Command	Description
npm run newsletter:send <slug>	Send a blog post to all subscribers
npm run newsletter:send:stats	Send weekly stats summary to your inbox

Troubleshooting

Emails not sending:

1. Verify AGENTMAIL_API_KEY and AGENTMAIL_INBOX are set in Convex dashboard
2. Check Convex function logs for error messages
3. Ensure your inbox is active in AgentMail dashboard

Contact form not appearing:

1. Verify contactForm: true is in frontmatter
2. Check siteConfig.contactForm.enabled is true
3. Run npm run sync to sync frontmatter changes

Newsletter Admin not accessible:

1. Verify siteConfig.newsletterAdmin.enabled is true
2. Navigate to /newsletter-admin directly (hidden from nav by default)

Resources

• AgentMail Documentation
• AgentMail Quickstart
• AgentMail Sending & Receiving Email
• AgentMail Inboxes

Summary

AgentMail integration provides:

• Newsletter subscriptions and sending
• Contact forms on any post or page
• Automated weekly digests
• Developer notifications
• Admin UI for subscriber management
• CLI tools for sending newsletters and stats

All features use Convex environment variables for configuration. No hardcoded emails in your codebase.