Transactional Email API for AI Agents: A Mailpro™ v2 Guide

If you have read our guide to AI agents and the Mailpro™ APIs, you know the pattern: the model decides, your code sends. This article goes deep on one API, the Mailpro™ Email API v2, and walks through a working setup for transactional and campaign email driven by Claude, GPT or any LLM that supports tool calling, with the exact endpoints and parameters.

TL;DR

• Base URL https://api.mailpro.com/v2, JSON responses, OAuth 2.0 bearer token (or the legacy IdClient + ApiKey).
• One email to one person: POST /send/sendmail.json. A saved template to a whole list: POST /send/campaign.json.
• Track each transactional email with GET /send/{IdSingleSend}/status.json or the email.delivered / email.bounced webhooks.
• Bulk-load contacts from an agent with POST /import/upload.json (CSV or XLSX, up to 50 MB).

AI-driven email: which use cases are worth it?

Smart order confirmations

A standard confirmation is a template. An agent can add a personal note ("Thanks for choosing the Blue XL, our customers' favourite") and relevant recommendations, then send it through the API. You keep the reliability of a structured template with the warmth of a written note.

Support auto-triage

When a ticket arrives, the agent classifies it, drafts a reply and, if it is confident and the topic is on an approved list, sends it. Everything else goes to a human with the draft attached.

Digests instead of floods

The agent reads a day of events (invoices, sign-ups, alerts) and sends one summary at 6 PM: "Today: 12 paid, 3 overdue, 2 to review." One email, no noise. The API handles delivery; the model handles the synthesis.

How do you set up the Email API v2 in 5 minutes?

1. Get credentials

In your Mailpro™ account, go to Settings → API access. For an agent, create an OAuth client and request only the scopes it needs, typically email:send and email:read. The legacy IdClient (numeric) and ApiKey (GUID) also work, but they are not scope-limited, so keep them for your own back-end scripts.

2. Check the connection

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

You should get your remaining email credits as JSON. A 401 means the token or key is wrong; a 403 insufficient_scope means the token lacks account:read.

3. Find your sender ID

Emails are sent from a validated sender address. GET /senderEmail/list.json returns them with their IDs; you will pass that ID as IDEmailExp.

Step by step: have Claude send a transactional email

The example uses Anthropic's Claude, but the same pattern works with OpenAI function calling or Gemini tool use: the SDK changes, the architecture does not.

1. Define the tool

tools = [{
  "name": "send_transactional_email",
  "description": "Send one email to one customer via Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Full HTML body"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Write the system prompt

You help customer-success agents write and send follow-up emails.
Only call send_transactional_email after the human confirms.
Be concise and friendly, and always include one clear call-to-action link.

3. Execute the call against /send/sendmail

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # from /senderEmail/list
            "EmailData":  args["to"],      # email,field1,field2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # track opens and clicks
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Useful optional fields: DatePlanned (ISO 8601) to schedule instead of sending now, ReplyTo, BodyText for a plain-text version, and attachments. Return the JSON to the model as the tool result so it can tell the user the email is on its way.

Wiring up transactional sends? Mailpro’s automated emails fire instantly on every trigger — receipts, confirmations, alerts — with delivery you can trust.

4. Confirm delivery

GET /send/8001/status.json returns delivered, bounced (with BounceType and the server's DiagCode), deferred, sent, scheduled or queued. Expect delivered about five minutes after handover. For real-time feedback, subscribe to the email.delivered and email.bounced webhooks instead of polling.

Campaigns: let the agent prepare, let a human press send

For a send to a whole list, the agent works with a saved template rather than raw HTML:

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned is optional: omit it and the campaign leaves immediately. A good pattern is to let the agent pick the list, the template and a send time based on the audience's time zone, then show the plan to a human who approves it. Scheduled campaigns can still be moved with PATCH /send/{IdSend}/reschedule.json or cancelled with POST /send/{IdSend}/cancel.json.

Personalisation with fields

In /send/sendmail, EmailData takes the address followed by up to 25 values ([email protected],Alice,Dupont,Paris) that fill the template's personalisation fields. In campaigns, the fields come from each contact's data in the list. The agent only needs to place the field in its HTML; the API fills it per recipient.

Bulk-import contacts from an agent upload

When the first step of a workflow is "add these 500 new leads", do not make 500 API calls. Send one file:

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

The file must be UTF-8 with a header row that includes Email; other columns map to the list's custom fields. The endpoint returns an ImportJobId immediately, processes the file in the background and calls your WebhookUrl with the counts of imported, skipped and invalid rows.

Pitfalls and tips

• Unsubscribed addresses are refused. The API answers "Email address unsubscribed." with a 400. Tell the agent this is final, not an error to retry.
• Watch the credits. "Not enough credit available." comes back as a 403. Subscribe to the credits.low webhook so a human tops up before the agent hits the wall.
• Mind the request quota. API calls count against a monthly quota shared by the Email, CRM and SMS APIs (GET /account/limits.json). Cap tool calls per conversation and back off on 429.
• Stick to JSON. XML is supported with the .xml suffix, but JSON is simpler for LLM tool output.
• Authenticate your domain. Personalised AI-written emails still need SPF, DKIM and DMARC to reach the inbox; see our deliverability troubleshooting guide.

Case study (fictional): "NovaFit", a gym network with AI-written class reminders

NovaFit runs 40 gyms and sends a reminder 24 hours before each booked class. The reminders used to be one template ("Hi Anna, your yoga class is tomorrow at 7 AM"). The team put Claude behind the booking system: for each reminder, the agent reads the member's recent attendance and the class type, writes one personal line ("Last week you held the warrior pose a full minute, ready for the next level?") and sends the email with /send/sendmail. Bounces come back through the email.bounced webhook and are flagged to the front desk. Open rates on reminders rose from 46% to 63% and attendance went up 8 points, with no change in email volume.

Next steps

The Email API v2 handles sending. If your agent also needs to manage contacts, tags, segments and custom fields, read our CRM API v3 guide for AI. For text messages, see sending SMS with an AI agent. Weighing a managed platform against a raw sending service? See our guide to the best Amazon SES alternatives. Full reference: the Email API v2 documentation.