Agent Email Inbox Skill

The Agent Email Inbox skill lets an AI agent securely receive and act on inbound email through MailBlastr's webhook-based inbound architecture. Crucially, it bakes in security from the start: an inbox is untrusted input, and without guardrails anyone who knows your agent's address could send instructions the agent would execute.

Unlike polling, MailBlastr delivers inbound email via webhooks — your server is notified the moment a message arrives, with no cron jobs and no wasted API calls checking an empty inbox.

How to give an agent this skill

This is a security *pattern*, not a package to install. Capture the architecture and security levels below as a SKILL.md (or equivalent context file) in your repo and load it into your agent's context alongside the MailBlastr skill. It builds entirely on primitives that already exist: inbound webhooks (email.received), the Receiving API, and the `mailblastr` SDK or native HTTP for replies.

Document each security level with full implementation code in your skill file so the agent can apply the right one. Because the underlying calls work over native HTTP, the patterns work in any language.

Architecture

Email -> MailBlastr -> Webhook -> Your Server -> Validate
                                                    |
                                            Process or Reject

Your agent processes only emails that pass your chosen security level. Rejected emails are logged and silently acknowledged with a 200 so MailBlastr does not retry the webhook.

Security levels

Pick a security level before you set up your webhook endpoint. Start with Level 1 and relax only if you must.

Minimal handler

A minimal webhook handler verifies the signature, checks the sender against an allowlist (Level 1), and fetches the full message before handing it to the agent. With MailBlastr you verify the signature against your webhook signing secret, then react to the email.received event.

import { MailBlastr } from 'mailblastr';
const mb = new MailBlastr(process.env.MAILBLASTR_API_KEY);

const ALLOWED_SENDERS = ['your@email.com'];

async function handler(req) {
  const payload = await req.text();

  // Verify the webhook signature against your signing secret before trusting it.
  if (!verifyMailblastrSignature(payload, req.headers, process.env.MAILBLASTR_WEBHOOK_SECRET)) {
    return new Response('invalid signature', { status: 400 });
  }

  const event = JSON.parse(payload);

  if (event.type === 'email.received') {
    // Level 1: silently drop anything not on the allowlist.
    if (!ALLOWED_SENDERS.includes(event.data.from.toLowerCase())) {
      return new Response('OK', { status: 200 });
    }

    // Fetch the full inbound message, then hand it to the agent.
    const { data: email } = await mb.emails.receiving.get(event.data.email_id);
    await processEmailForAgent(email);
  }

  return new Response('OK', { status: 200 });
}