# IvyMail: AI Agent Skill

IvyMail is a transactional email API. Use it to send emails programmatically.

**Base URL:** `https://api.ivymail.io`
**Auth:** `x-api-key` header
**Docs:** https://ivymail.io/docs

---

## Prerequisites

- An IvyMail API key (get one at https://ivymail.io/dashboard → API Keys)
- A verified sending domain (set up at https://ivymail.io/dashboard → Domains)

---

## Send an email

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

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `to` | `string[]` | Yes | Recipients (max 50) |
| `from_email` | `string` | Yes | Sender, e.g. `"Name <you@domain.com>"` |
| `subject` | `string` | Yes | Subject line |
| `html` | `string` | No | HTML body |
| `text` | `string` | No | Plain text body |
| `reply_to` | `string` | No | Reply-to address |

### Success response

```json
{
  "success": true,
  "data": {
    "message_id": "abc123-def456",
    "status": "sent"
  }
}
```

### Error response

```json
{
  "success": false,
  "error": "Description of what went wrong"
}
```

---

## Check send logs

```bash
curl https://api.ivymail.io/v1/send/logs \
  -H "x-api-key: $IVYMAIL_API_KEY"
```

Query params: `limit` (1–100), `offset`, `type` (send/bounce/complaint), `status` (sent/delivered/bounced/complained/suppressed/failed).

---

## Check send stats

```bash
curl https://api.ivymail.io/v1/send/stats \
  -H "x-api-key: $IVYMAIL_API_KEY"
```

Returns: `total_sent`, `delivered`, `bounced`, `complained`, `suppressed`, `failed`.

---

## Rate limits

| Endpoint | Limit |
|----------|-------|
| `POST /v1/send` | 30/min |
| All other endpoints | 60/min |

On `429`, retry with exponential backoff.

---

## Full setup flow (for new users)

1. Sign up at https://ivymail.io/dashboard
2. A workspace is created automatically
3. Go to **API Keys** → **Create API Key** → copy the key
4. Go to **Domains** → **Add Domain** → enter your sending domain
5. Add the 3 DNS records IvyMail provides (TXT for verification, TXT for SPF, CNAME for DKIM)
6. Click **Check Status** to verify the domain
7. Set `IVYMAIL_API_KEY` in your environment
8. Send your first email with the curl command above

---

## Tips for agents

- Always ask the user for their API key. Never hardcode or guess it.
- Always include a `text` fallback alongside `html`
- Check the `success` field in every response before proceeding
- If `status` is `suppressed`, the recipient previously bounced/complained. Do not retry.
- Store the API key in an environment variable (`IVYMAIL_API_KEY`)

---

## Links

- Dashboard: https://ivymail.io/dashboard
- Full docs: https://ivymail.io/docs
- API reference: https://ivymail.io/docs/api-reference
- Agent guide: https://ivymail.io/docs/agent-integration