Skip to main content

Receive your first email

1. Create a webhook endpoint​

Sign in to Wildmail, open Webhooks, and create an endpoint for your application. Destinations must be publicly reachable HTTPS URLs on port 443.

Save the signing secret when Wildmail displays it. It is shown once. Store it in your application's secret manager, separately from your Wildmail API key. Implement the webhook receiver example before receiving real data.

Select Send test. This sends an email.test event and checks endpoint reachability and signature verification. It does not receive email through SMTP or consume an inbound message.

2. Assign your hosted address​

Open Receiving domains and attach the active endpoint to your hosted test address. Copy the exact address shown in your account.

You do not need DNS access for this address. Only your assigned address accepts mail. The hosted domain is not a customer catch-all. Hosted messages count toward your account's monthly message allowance.

3. Send an email​

Send an email from your normal email client to that address. Include a subject, a short body, and an optional small attachment. Wildmail parses and stores the email before accepting it. Wildmail then sends an email.received event to the endpoint.

Use Messages to inspect the received email and authentication results. Use Deliveries to inspect HTTP attempts and replay retained events. A successful SMTP submission and a successful webhook delivery are separate outcomes.

For this walkthrough, keep retention at 1 or more days so you can inspect content and try replay. With 0-day retention, Wildmail allows at most one webhook attempt after parsing. Its standard payload includes inline bodies and base64 attachments instead of download URLs. It does not retry or allow replay, and message content is cleared after the attempt settles or its deadline passes. See usage and retention.

4. Read state through the API​

Create an API key with domains:read, messages:read, and deliveries:read. The following shell examples assume the Wildmail application URL and key are already set:

export WILDMAIL_BASE_URL="https://wildmail.app"
export WILDMAIL_API_KEY="your-api-key"

curl --fail-with-body "$WILDMAIL_BASE_URL/api/hosted-address" \
-H "Authorization: Bearer $WILDMAIL_API_KEY"

curl --fail-with-body "$WILDMAIL_BASE_URL/api/messages" \
-H "Authorization: Bearer $WILDMAIL_API_KEY"

curl --fail-with-body "$WILDMAIL_BASE_URL/api/deliveries?page=1" \
-H "Authorization: Bearer $WILDMAIL_API_KEY"

Keep API keys on your server. See the API reference for all routes and custom domains to use your own address.