Poll for new message (check every 5 seconds, max 60 seconds) Skill

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

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:

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

Read Message Content (HTML)

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)

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

Get Message Headers as JSON

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

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)

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

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

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

Response:

{
  "_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

curl -s "https://mailsac.com/api/addresses" --header "Mailsac-Key: $MAILSAC_TOKEN" | jq .

Release a Private Address

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

Release Address and Delete All Messages

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:

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

Then run:

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:

{
  "webhook": ""
}

Then run:

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:

{
  "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

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

Response:

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

Check if Email is Disposable

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:

{
  "to": "recipient@example.com",
  "from": "sender@mailsac.com",
  "subject": "Test Email",
  "text": "This is the email body content."
}

Then run:

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

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

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

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

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

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

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

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

[
  {
    "_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

{
  "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

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

Agent Skills: Poll for new message (check every 5 seconds, max 60 seconds)

Install this agent skill to your local

Skill Files

Troubleshooting

How to Use

1. Messages - Read Emails

List Messages in Inbox

Read Message Content (Plain Text)

Read Message Content (HTML)

Get Raw SMTP Message (with headers and attachments)

Get Message Headers as JSON

2. Messages - Delete

Delete Single Message

Purge Entire Inbox (Enhanced Address only)

Delete All Messages in Custom Domain

3. Private Addresses - Reserve and Release

Reserve a Private Address

List Your Private Addresses

Release a Private Address

Release Address and Delete All Messages

4. Webhook Forwarding

Set Webhook for Private Address

Remove Webhook

5. Email Validation

Validate Single Email

Check if Email is Disposable

6. Send Email (Outgoing)

7. Attachments

Get Attachment by MD5 Hash

Get Raw Message and Parse Attachments

8. Star/Save Messages

Star a Message

Practical Examples

Wait for Email and Extract Verification Code

List Recent Messages with Subject and Sender

Clean Up Test Inbox Before Tests

Check if Email Service is Disposable

Response Format

Message List Response

Validation Response

Limits and Quotas

Guidelines