mailsac

---
name: mailsac
description: MailSac API for disposable email testing. Use when user mentions "MailSac",
  "test email", "disposable email", or email testing.
---

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name MAILSAC_TOKEN` or `zero doctor check-connector --url https://mailsac.com/api/addresses/test@mailsac.com/messages --method GET`

## How to Use

All examples below assume you have `MAILSAC_TOKEN` set.

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

## 1. Messages - Read Emails

Retrieve and read emails from any inbox.

### List Messages in Inbox

```bash
curl -s "https://mailsac.com/api/addresses/test@mailsac.com/messages" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .
```

### Read Message Content (Plain Text)

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

```bash
curl -s "https://mailsac.com/api/text/test@mailsac.com/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Read Message Content (HTML)

```bash
curl -s "https://mailsac.com/api/body/test@mailsac.com/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

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

```bash
curl -s "https://mailsac.com/api/raw/test@mailsac.com/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Get Message Headers as JSON

```bash
curl -s "https://mailsac.com/api/headers/test@mailsac.com/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN" | 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
curl -s -X DELETE "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Purge Entire Inbox (Enhanced Address only)

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/test@mailsac.com/messages" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

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

### Delete All Messages in Custom Domain

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

## 3. Private Addresses - Reserve and Release

Manage private email addresses for exclusive use.

### Reserve a Private Address

```bash
curl -s -X POST "https://mailsac.com/api/addresses/mytest@mailsac.com" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .
```

**Response:**

```json
{
  "_id": "mytest@mailsac.com",
  "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
curl -s "https://mailsac.com/api/addresses" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .
```

### Release a Private Address

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/mytest@mailsac.com" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Release Address and Delete All Messages

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/mytest@mailsac.com?deleteAddressMessages=true" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

## 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
curl -s -X PUT "https://mailsac.com/api/private-address-forwarding/mytest@mailsac.com" --header "Mailsac-Key: $MAILSAC_TOKEN" --header "Content-Type: application/json" -d @/tmp/mailsac_webhook.json | jq .
```

### Remove Webhook

Write to `/tmp/mailsac_webhook.json`:

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

Then run:

```bash
curl -s -X PUT "https://mailsac.com/api/private-address-forwarding/mytest@mailsac.com" --header "Mailsac-Key: $MAILSAC_TOKEN" --header "Content-Type: application/json" -d @/tmp/mailsac_webhook.json | jq .
```

**Webhook Payload Format:**

```json
{
  "text": "Email body content",
  "subject": "Email subject",
  "from": [{"address": "sender@example.com", "name": "Sender Name"}],
  "to": [{"address": "recipient@mailsac.com", "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
curl -s "https://mailsac.com/api/validations/addresses/test@example.com" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .
```

**Response:**

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

### Check if Email is Disposable

```bash
curl -s "https://mailsac.com/api/validations/addresses/test@mailsac.com" --header "Mailsac-Key: $MAILSAC_TOKEN" | 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": "recipient@example.com",
  "from": "sender@mailsac.com",
  "subject": "Test Email",
  "text": "This is the email body content."
}
```

Then run:

```bash
curl -s -X POST "https://mailsac.com/api/outgoing-messages" --header "Mailsac-Key: $MAILSAC_TOKEN" --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
curl -s "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>/attachments/<attachment-md5>" --header "Mailsac-Key: $MAILSAC_TOKEN" > attachment.bin
```

### Get Raw Message and Parse Attachments

```bash
curl -s "https://mailsac.com/api/raw/test@mailsac.com/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN" > 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
curl -s -X PUT "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>/star" --header "Mailsac-Key: $MAILSAC_TOKEN" | 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=$(curl -s "https://mailsac.com/api/addresses/$EMAIL/messages" --header "Mailsac-Key: $MAILSAC_TOKEN")
  COUNT=$(echo "$MESSAGES" | jq 'length')
  if [ "$COUNT" -gt "0" ]; then
    MESSAGE_ID=$(echo "$MESSAGES" | jq -r '.[0]._id')
    echo "Message received: $MESSAGE_ID"
    curl -s "https://mailsac.com/api/text/$EMAIL/$MESSAGE_ID" --header "Mailsac-Key: $MAILSAC_TOKEN"
    break
  fi
  echo "Waiting for email... ($i/12)"
  sleep 5
done
```

### List Recent Messages with Subject and Sender

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

### Clean Up Test Inbox Before Tests

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/test@mailsac.com/messages" --header "Mailsac-Key: $MAILSAC_TOKEN"
echo "Inbox purged"
```

### Check if Email Service is Disposable

```bash
curl -s "https://mailsac.com/api/validations/addresses/user@tempmail.com" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq 'if .isDisposable then "DISPOSABLE" else "LEGITIMATE" end'
```

## Response Format

### Message List Response

```json
[
  {
    "_id": "message-id-here",
    "from": [{"address": "sender@example.com", "name": "Sender"}],
    "to": [{"address": "test@mailsac.com", "name": ""}],
    "subject": "Email Subject",
    "received": "2024-01-01T00:00:00.000Z",
    "size": 1234,
    "attachments": []
  }
]
```

### Validation Response

```json
{
  "email": "test@mailsac.com",
  "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