curl Examples

Common API operations using curl.

These examples assume you have API_URL and TOKEN environment variables set:

export API_URL="https://your-api-url"
export TOKEN="your-api-key"

List emails in an inbox

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test" | jq

Wait for an email to arrive

Long-poll for up to 15 seconds:

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&wait=true&timeout=15" | jq

Filter by sender

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&sender=noreply@example.com" | jq

Filter by subject

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&subject=Verify" | jq

Filter emails with attachments

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&hasAttachments=true" | jq

Get a specific email

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails/abc123@mail.example.com" | jq

Download raw .eml file

The -L flag follows the redirect to the pre-signed S3 URL:

curl -L -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails/abc123@mail.example.com/raw" -o email.eml

Download an attachment

curl -L -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails/abc123@mail.example.com/attachments/invoice.pdf" -o invoice.pdf

Paginate through results

# First page
RESPONSE=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&limit=10")

echo "$RESPONSE" | jq '.emails | length'

# Next page using cursor
CURSOR=$(echo "$RESPONSE" | jq -r '.nextCursor')
curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test&limit=10&cursor=$CURSOR" | jq

Delete a single email

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails/abc123@mail.example.com" | jq

Delete all emails in an inbox

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API_URL/v1/emails?inbox=test" | jq

Health check

No authentication required:

curl -s "$API_URL/health" | jq