Inbound Email API: How to Receive Email Programmatically for AI Agents

An inbound email API lets your application receive email programmatically. Instead of polling a mailbox or scraping an inbox, incoming messages are delivered to your code in real time via webhooks. For AI agents that need to read, understand, and respond to email, an inbound email API is the foundational building block that makes autonomous email workflows possible.

This guide explains how inbound email APIs work, how to set one up with AgentSend, and why the per-inbox webhook model is a better fit for AI agents than traditional approaches like IMAP polling or domain-level inbound parsing.

What Is an Inbound Email API?

An inbound email API is a service that accepts incoming email on your behalf and delivers it to your application as structured data. The typical flow works like this: MX records direct incoming mail to the API provider's servers, the provider parses the raw email into a structured payload (sender, subject, body, attachments, headers), and then delivers that payload to a webhook URL you configure.

The key advantage over traditional email receiving is that your application never manages a mail server. There is no IMAP connection to maintain, no POP3 polling interval to tune, and no raw MIME parsing to implement. You receive a clean JSON payload via HTTP POST, process it, and respond with a 200 status code. That is the entire integration.

For AI agents, this matters because agents need to react to incoming email in real time. A customer support agent cannot wait five minutes for the next IMAP poll to discover a new ticket. An email webhook API delivers the message the moment it arrives, letting your agent begin processing immediately.

How Inbound Email Works in AgentSend

AgentSend's receive email API is built around per-inbox webhooks. When you create an inbox, you can configure a webhook URL that receives every inbound message for that specific inbox. Each inbox is isolated — there is no shared routing layer where you need to inspect recipient addresses and dispatch to the correct handler.

Every webhook delivery includes an HMAC signature in the X-AgentSend-Signature header. Your application verifies this signature using your inbox's webhook secret to confirm the payload was sent by AgentSend and was not tampered with in transit. If your endpoint is temporarily unavailable, AgentSend retries delivery with exponential backoff for up to 24 hours.

Setting Up Inbound Email

Getting started with AgentSend's email inbox API takes two steps: create an inbox with a webhook URL, then handle the incoming payloads.

Step 1: Create an Inbox with a Webhook

Using cURL:

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Using Python:

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

Step 2: Handle the Webhook Payload

When an email arrives, AgentSend posts a JSON payload to your webhook URL. Here is a minimal Python handler using Flask:

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

Inbound Email API vs Traditional Approaches

There are several ways to receive email programmatically. Here is how the most common approaches compare for AI agent use cases.

The critical difference is isolation. Mailgun and SendGrid both operate at the domain level: you point your domain's MX records to their servers, and all incoming mail for that domain hits a single webhook endpoint. You are responsible for inspecting the recipient address in each payload and routing it to the correct agent. With AgentSend, each inbox has its own webhook, its own signing secret, and its own thread history. There is no routing logic to build or maintain.

Email Inbox API: Creating Inboxes Programmatically

One of the most powerful aspects of an email inbox API is the ability to create inboxes on the fly. When your platform onboards a new customer, provisions a new AI agent, or spins up a new workflow, you can create a dedicated inbox with a single API call. Each inbox gets its own email address automatically — no DNS configuration, no manual setup, no waiting for propagation.

This is particularly useful for multi-agent architectures. A customer support system might create separate inboxes for billing questions, technical support, and account management. Each inbox routes to a specialized agent with its own webhook endpoint and its own conversation history. Scaling from one agent to fifty is a loop of API calls, not a DNS migration project.

Use Cases for Inbound Email APIs

An inbound email API unlocks a range of autonomous agent workflows that are difficult or impossible to build with traditional email infrastructure.

• Customer support agents — Receive support tickets via email, classify intent, resolve common questions automatically, and escalate complex issues to human agents with full thread context.
• Research agents — Subscribe to newsletters, receive reports, and process incoming information feeds. The agent reads each email, extracts relevant data, and updates a knowledge base without human intervention.
• Scheduling agents — Receive meeting requests and availability responses via email. The agent parses the content, checks calendars, and sends confirmation replies — all through its own dedicated email address.
• Outbound-first agents with reply handling — Agents that send cold outreach, follow-up sequences, or notifications can receive and process replies through the same inbox, maintaining full conversation context.

In each case, the inbound email API eliminates the infrastructure burden. Your agent code focuses on understanding and responding to messages, not on maintaining IMAP connections, parsing MIME, or routing emails to the correct handler.