Mailsac

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:

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:

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

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