mailsac

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name MAILSAC_TOKEN` or `zero doctor check-connector --url https://mailsac.com/api/addresses/[email protected]/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/[email protected]/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/[email protected]/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Read Message Content (HTML)

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

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

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

### Get Message Headers as JSON

```bash
curl -s "https://mailsac.com/api/headers/[email protected]/<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/[email protected]/messages/<message-id>" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Purge Entire Inbox (Enhanced Address only)

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]/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/[email protected]" --header "Mailsac-Key: $MAILSAC_TOKEN" | 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
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/[email protected]" --header "Mailsac-Key: $MAILSAC_TOKEN"
```

### Release Address and Delete All Messages

```bash
curl -s -X DELETE "https://mailsac.com/api/addresses/[email protected]?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/[email protected]" --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/[email protected]" --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": "[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
curl -s "https://mailsac.com/api/validations/addresses/[email protected]" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .
```

**Response:**

```json
{
  "email": "[email protected]",
  "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/[email protected]" --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": "[email protected]",
  "from": "[email protected]",
  "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/[email protected]/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/[email protected]/<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/[email protected]/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/[email protected]/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@ma