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

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

export MAILSAC_API_KEY="your-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

curl -s "https://mailsac.com/api/addresses/test@mailsac.com/messages" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)" | 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: $(printenv MAILSAC_API_KEY)"

Read Message Content (HTML)

curl -s "https://mailsac.com/api/body/test@mailsac.com/<message-id>" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)"

Get Raw SMTP Message (with headers and attachments)

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

Get Message Headers as JSON

curl -s "https://mailsac.com/api/headers/test@mailsac.com/<message-id>" --header "Mailsac-Key: $(printenv 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

curl -s -X DELETE "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)"

Purge Entire Inbox (Enhanced Address only)

curl -s -X DELETE "https://mailsac.com/api/addresses/test@mailsac.com/messages" --header "Mailsac-Key: $(printenv 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

curl -s -X PUT "https://mailsac.com/api/domains/yourdomain.com/delete-all-domain-mail" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)"

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: $(printenv MAILSAC_API_KEY)" | 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: $(printenv MAILSAC_API_KEY)" | jq .

Release a Private Address

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

Release Address and Delete All Messages

curl -s -X DELETE "https://mailsac.com/api/addresses/mytest@mailsac.com?deleteAddressMessages=true" --header "Mailsac-Key: $(printenv 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:

{
  "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: $(printenv MAILSAC_API_KEY)" --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: $(printenv MAILSAC_API_KEY)" --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: $(printenv MAILSAC_API_KEY)" | 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: $(printenv 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:

{
  "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: $(printenv 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

curl -s "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>/attachments/<attachment-md5>" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)" > attachment.bin

Get Raw Message and Parse Attachments

curl -s "https://mailsac.com/api/raw/test@mailsac.com/<message-id>" --header "Mailsac-Key: $(printenv 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

curl -s -X PUT "https://mailsac.com/api/addresses/test@mailsac.com/messages/<message-id>/star" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)" | 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: $(printenv 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"
    curl -s "https://mailsac.com/api/text/$EMAIL/$MESSAGE_ID" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)"
    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: $(printenv MAILSAC_API_KEY)" | 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: $(printenv MAILSAC_API_KEY)"
echo "Inbox purged"

Check if Email Service is Disposable

curl -s "https://mailsac.com/api/validations/addresses/user@tempmail.com" --header "Mailsac-Key: $(printenv MAILSAC_API_KEY)" | 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