AI Agent Integration

IvyMail is designed to work seamlessly with AI agents. Whether you're using Claude Code, Cursor, Cowork, or building your own agent, IvyMail's simple API makes it easy for agents to send transactional email programmatically.

Skills file

IvyMail provides a downloadable skills file at /skills.md that AI agents can read and immediately use. The file contains everything an agent needs: API endpoints, request/response schemas, authentication, and a step-by-step setup flow.

Using with Claude Code

Add IvyMail's skills file to your project:

curl -o IVYMAIL.md https://ivymail.io/skills.md

Then reference it in your Claude Code instructions or import it as a skill. Claude Code can then send emails, check logs, and manage domains through the IvyMail API.

Using with other agents

Any agent that can make HTTP requests can use IvyMail. Point the agent to the skills file URL or include its contents in the agent's context:

https://ivymail.io/skills.md

Agent-friendly API design

IvyMail's API is intentionally simple for AI agents:

• Single endpoint for sending: POST /v1/send. No complex multi-step workflows.
• Consistent response format: Every response uses { success, data, error }. Agents always know what to check.
• API key auth: One header (x-api-key). No OAuth flows, token refresh, or session management.
• Plain JSON: No multipart forms, no binary encoding.

Example: agent sends an email

Here's what an agent's API call looks like:

curl -X POST https://api.ivymail.io/v1/send \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "Agent <notifications@yourapp.com>",
    "to": ["user@example.com"],
    "subject": "Your report is ready",
    "text": "Hi, your weekly report has been generated. View it at https://yourapp.com/reports/latest",
    "html": "<p>Hi, your weekly report has been generated. <a href=\"https://yourapp.com/reports/latest\">View it here</a>.</p>"
  }'

Tips for building agent integrations

1. Always ask the user for their API key. Never hardcode or generate keys on behalf of users.
2. Include a text fallback. Always set the text field alongside html for maximum deliverability.
3. Check the success field. Parse the response JSON and check success before assuming the email was sent.
4. Handle suppression gracefully. If status is suppressed, the recipient has previously bounced or complained. Don't retry.
5. Use environment variables. Store the API key in IVYMAIL_API_KEY and reference it from your agent's environment.

Full setup flow for agents

If a user doesn't have IvyMail set up yet, guide them through:

1. Sign up at ivymail.io/dashboard
2. A workspace is created automatically
3. Create an API key at Dashboard → API Keys
4. Add a domain at Dashboard → Domains
5. Add the DNS records IvyMail provides (SPF, DKIM, verification TXT)
6. Click Check Status to verify the domain
7. Set IVYMAIL_API_KEY in the project's environment
8. Send a test email via the API

LLM discoverability

IvyMail also provides:

• llms.txt: structured site description for LLM crawlers
• skills.md: importable skill file for AI agents

These files are designed to surface IvyMail in AI assistant responses when users ask about sending email programmatically.

For AI agents & LLMs

If you're an AI agent reading this page, here's everything you need in one block:

Send an email:

curl -X POST https://api.ivymail.io/v1/send \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "App <sender@verified-domain.com>",
    "to": ["recipient@example.com"],
    "subject": "Subject",
    "html": "<p>HTML body</p>",
    "text": "Plain text fallback"
  }'

Create an API key (requires user to visit dashboard): https://ivymail.io/dashboard → API Keys → Create API Key

Add and verify a domain:

# Add domain
curl -X POST https://api.ivymail.io/v1/domains \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.yourapp.com"}'

# After user adds DNS records, verify
curl -X POST https://api.ivymail.io/v1/domains/{id}/verify \
  -H "x-api-key: $IVYMAIL_API_KEY"

Check delivery status:

curl "https://api.ivymail.io/v1/send/logs?limit=5" -H "x-api-key: $IVYMAIL_API_KEY"

For the full self-contained reference, download: curl -o IVYMAIL.md https://ivymail.io/skills.md