playbooks

home / skills / vm0-ai / vm0-skills / mailsac

mailsac skill

/mailsac

This skill helps you manage disposable emails for testing with Mailsac via curl, enabling inbox reading, validation, webhooks, and automation.

npx playbooks add skill vm0-ai/vm0-skills --skill mailsac

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
10.8 KB
---
name: mailsac
description: Mailsac disposable email API via curl. Use this skill to receive test emails, validate email addresses, manage inboxes, and automate email-based QA testing.
vm0_secrets:
  - MAILSAC_API_KEY
---

# Mailsac

Use the Mailsac API via direct `curl` calls to **manage disposable email addresses for testing and QA automation**.

> Official docs: `https://docs.mailsac.com/`

---

## When to Use

Use this skill when you need to:

- **Receive test emails** in disposable inboxes
- **Validate email addresses** (check format and disposable status)
- **Automate email verification flows** in E2E tests
- **Configure webhooks** for real-time email notifications
- **Manage private email addresses** for testing

---

## Prerequisites

1. Sign up at https://mailsac.com/
2. Get your API key from the dashboard (Account > API Key)

```bash
export MAILSAC_API_KEY="your-api-key"
```

---

> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://mailsac.com/api/..." --header "Mailsac-Key: $MAILSAC_API_KEY"'
> ```

## How to Use

All examples below assume you have `MAILSAC_API_KEY` set.

Base URL: `https://mailsac.com`

---

## 1. Messages - Read Emails

Retrieve and read emails from any inbox.

### List Messages in Inbox

```bash
bash -c 'curl -s "https://mailsac.com/api/addresses/[email protected]/messages" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

### Read Message Content (Plain Text)

Replace `<message-id>` with the actual messageId from the list:

```bash
bash -c 'curl -s "https://mailsac.com/api/text/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

### Read Message Content (HTML)

```bash
bash -c 'curl -s "https://mailsac.com/api/body/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

### Get Raw SMTP Message (with headers and attachments)

```bash
bash -c 'curl -s "https://mailsac.com/api/raw/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

### Get Message Headers as JSON

```bash
bash -c 'curl -s "https://mailsac.com/api/headers/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

**Message Format Endpoints:**

| Endpoint | Description |
|----------|-------------|
| `/api/text/{email}/{messageId}` | Plain text body |
| `/api/body/{email}/{messageId}` | Sanitized HTML body |
| `/api/dirty/{email}/{messageId}` | Unsanitized HTML with inlined images |
| `/api/raw/{email}/{messageId}` | Complete SMTP message |
| `/api/headers/{email}/{messageId}` | JSON headers |

---

## 2. Messages - Delete

Delete single messages or purge entire inboxes.

### Delete Single Message

```bash
bash -c 'curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]/messages/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

### Purge Entire Inbox (Enhanced Address only)

```bash
bash -c 'curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]/messages" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

Note: Starred messages will NOT be purged. Unstar them first if you want to delete everything.

### Delete All Messages in Custom Domain

```bash
bash -c 'curl -s -X PUT "https://mailsac.com/api/domains/yourdomain.com/delete-all-domain-mail" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

---

## 3. Private Addresses - Reserve and Release

Manage private email addresses for exclusive use.

### Reserve a Private Address

```bash
bash -c 'curl -s -X POST "https://mailsac.com/api/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

**Response:**

```json
{
  "_id": "[email protected]",
  "owner": "your-username",
  "forward": null,
  "webhook": null,
  "webhookSlack": null,
  "enablews": false,
  "created": "2024-01-01T00:00:00.000Z",
  "updated": "2024-01-01T00:00:00.000Z"
}
```

### List Your Private Addresses

```bash
bash -c 'curl -s "https://mailsac.com/api/addresses" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

### Release a Private Address

```bash
bash -c 'curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

### Release Address and Delete All Messages

```bash
bash -c 'curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]?deleteAddressMessages=true" --header "Mailsac-Key: $MAILSAC_API_KEY"'
```

---

## 4. Webhook Forwarding

Configure webhooks to receive email notifications in real-time.

### Set Webhook for Private Address

Write to `/tmp/mailsac_webhook.json`:

```json
{
  "webhook": "https://your-server.com/email-webhook"
}
```

Then run:

```bash
bash -c 'curl -s -X PUT "https://mailsac.com/api/private-address-forwarding/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY" --header "Content-Type: application/json" -d @/tmp/mailsac_webhook.json' | jq .
```

### Remove Webhook

Write to `/tmp/mailsac_webhook.json`:

```json
{
  "webhook": ""
}
```

Then run:

```bash
bash -c 'curl -s -X PUT "https://mailsac.com/api/private-address-forwarding/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY" --header "Content-Type: application/json" -d @/tmp/mailsac_webhook.json' | jq .
```

**Webhook Payload Format:**

```json
{
  "text": "Email body content",
  "subject": "Email subject",
  "from": [{"address": "[email protected]", "name": "Sender Name"}],
  "to": [{"address": "[email protected]", "name": ""}],
  "headers": {},
  "messageId": "unique-message-id",
  "date": "2024-01-01T00:00:00.000Z",
  "receivedDate": "2024-01-01T00:00:00.000Z",
  "raw": "Full RFC-formatted email"
}
```

---

## 5. Email Validation

Validate email addresses and detect disposable email services.

### Validate Single Email

```bash
bash -c 'curl -s "https://mailsac.com/api/validations/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

**Response:**

```json
{
  "email": "[email protected]",
  "isValidFormat": true,
  "isDisposable": false,
  "disposableDomains": [],
  "aliases": [],
  "domain": "example.com",
  "local": "test"
}
```

### Check if Email is Disposable

```bash
bash -c 'curl -s "https://mailsac.com/api/validations/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq '{email, isDisposable}'
```

**Validation Response Fields:**

| Field | Description |
|-------|-------------|
| `isValidFormat` | Email syntax is valid |
| `isDisposable` | Email is from a disposable service |
| `disposableDomains` | List of identified disposable domains |
| `aliases` | Domain aliases and IP addresses |
| `domain` | Domain part of email |
| `local` | Local part of email |

---

## 6. Send Email (Outgoing)

Send emails via API (requires outgoing message credits).

Write to `/tmp/mailsac_outgoing.json`:

```json
{
  "to": "[email protected]",
  "from": "[email protected]",
  "subject": "Test Email",
  "text": "This is the email body content."
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://mailsac.com/api/outgoing-messages" --header "Mailsac-Key: $MAILSAC_API_KEY" --header "Content-Type: application/json" -d @/tmp/mailsac_outgoing.json' | jq .
```

Note: Sending requires purchased credits unless sending within your custom domain.

---

## 7. Attachments

Download attachments from received emails.

### Get Attachment by MD5 Hash

```bash
bash -c 'curl -s "https://mailsac.com/api/addresses/[email protected]/messages/<message-id>/attachments/<attachment-md5>" --header "Mailsac-Key: $MAILSAC_API_KEY"' > attachment.bin
```

### Get Raw Message and Parse Attachments

```bash
bash -c 'curl -s "https://mailsac.com/api/raw/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_API_KEY"' > message.eml
```

Note: For public addresses, attachments must be downloaded via API; they are not viewable on the website.

---

## 8. Star/Save Messages

Prevent messages from being auto-deleted by starring them.

### Star a Message

```bash
bash -c 'curl -s -X PUT "https://mailsac.com/api/addresses/[email protected]/messages/<message-id>/star" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq .
```

---

## Practical Examples

### Wait for Email and Extract Verification Code

```bash
EMAIL="test-$(date +%s)@mailsac.com"
echo "Use this email for registration: $EMAIL"

# Poll for new message (check every 5 seconds, max 60 seconds)
for i in $(seq 1 12); do
  MESSAGES=$(bash -c 'curl -s "https://mailsac.com/api/addresses/'"$EMAIL"'/messages" --header "Mailsac-Key: $MAILSAC_API_KEY"')
  COUNT=$(echo "$MESSAGES" | jq 'length')
  if [ "$COUNT" -gt "0" ]; then
    MESSAGE_ID=$(echo "$MESSAGES" | jq -r '.[0]._id')
    echo "Message received: $MESSAGE_ID"
    bash -c 'curl -s "https://mailsac.com/api/text/'"$EMAIL"'/'"$MESSAGE_ID"'" --header "Mailsac-Key: $MAILSAC_API_KEY"'
    break
  fi
  echo "Waiting for email... ($i/12)"
  sleep 5
done
```

### List Recent Messages with Subject and Sender

```bash
bash -c 'curl -s "https://mailsac.com/api/addresses/[email protected]/messages" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq '.[] | {subject, from: .from[0].address, received: .received}'
```

### Clean Up Test Inbox Before Tests

```bash
bash -c 'curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]/messages" --header "Mailsac-Key: $MAILSAC_API_KEY"'
echo "Inbox purged"
```

### Check if Email Service is Disposable

```bash
bash -c 'curl -s "https://mailsac.com/api/validations/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_API_KEY"' | jq 'if .isDisposable then "DISPOSABLE" else "LEGITIMATE" end'
```

---

## Response Format

### Message List Response

```json
[
  {
    "_id": "message-id-here",
    "from": [{"address": "[email protected]", "name": "Sender"}],
    "to": [{"address": "[email protected]", "name": ""}],
    "subject": "Email Subject",
    "received": "2024-01-01T00:00:00.000Z",
    "size": 1234,
    "attachments": []
  }
]
```

### Validation Response

```json
{
  "email": "[email protected]",
  "isValidFormat": true,
  "isDisposable": true,
  "disposableDomains": ["mailsac.com"],
  "aliases": ["104.197.186.12"],
  "domain": "mailsac.com",
  "local": "test"
}
```

---

## Limits and Quotas

| Type | Limit |
|------|-------|
| Public address message retention | 4 days |
| Public inbox max messages | 6 |
| Max message size | 2.5 MB |
| Operations quota reset | 1st of each month (UTC) |

---

## Guidelines

1. **Public vs Private**: Public addresses are accessible by anyone; use private addresses for sensitive test data
2. **Starred messages**: Star important messages to prevent auto-deletion
3. **Rate limits**: Free accounts may experience throttling; paid plans have higher limits
4. **Webhook reliability**: Check Recent Activity page for webhook debugging
5. **Attachments security**: For security reasons, attachments on public addresses require API access
6. **Operations count**: Listing messages + reading content = 2 API operations

Overview

This skill lets you interact with the Mailsac disposable email API using curl to receive test emails, validate addresses, manage inboxes, and automate email-based QA. It’s built for CI, end-to-end testing, and lightweight automation where disposable or private test addresses are needed. Use simple curl commands to list, read, delete, reserve, and webhook-forward messages without any SDK.

How this skill works

Commands call Mailsac API endpoints via curl with your MAILSAC_API_KEY environment variable. You can list inbox messages, fetch plain/text or HTML bodies, download raw SMTP data and attachments, star or delete messages, reserve private addresses, configure webhooks, validate addresses, and send outgoing messages when credits permit. Scripts commonly poll the messages endpoint to wait for verification emails and then extract codes or links.

When to use it

  • E2E or integration tests that require receiving email verification links or codes
  • Automated QA pipelines that need disposable inboxes to avoid polluting production email
  • Validate whether user-supplied emails are disposable before signup
  • Receive real-time email events via webhooks for test environments
  • Manage private test addresses to reserve exclusive inboxes for sensitive test data

Best practices

  • Always export MAILSAC_API_KEY as an environment variable and wrap piped curl calls in bash -c '...' to avoid environment variable clearing issues
  • Use private addresses for any sensitive or unique test accounts; public addresses are viewable by anyone
  • Star important messages to prevent automatic deletion during test runs
  • Purge or delete inboxes at test teardown to keep quotas low and avoid hitting retention limits
  • Poll messages with a reasonable interval and timeout (e.g., 5s interval, 60s total) to balance speed and rate limits

Example use cases

  • Poll a disposable inbox to extract a one-time verification code during signup tests
  • Reserve a private address, run tests that send invoices or confirmations, then release and delete messages
  • Configure a webhook to forward incoming test emails to a local test harness or CI job
  • Validate incoming user emails to block disposable providers before account creation
  • Download attachments from test emails and assert file contents in automated checks

FAQ

Do I need an API key?

Yes. Export MAILSAC_API_KEY from your account dashboard and include it in the Mailsac-Key header for all API calls.

Can I use public inboxes for sensitive tests?

No. Public addresses are readable by anyone. Use private/reserved addresses for sensitive data and exclusive use.