> For the complete documentation index, see [llms.txt](https://docs.mailofly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailofly.com/external-integrations/automation/webhooks.md).

# Webhooks

Receive real-time notifications when mail is sent, delivered, bounced, or fails — without polling mail logs.

{% hint style="warning" %}
**Webhooks are on the roadmap.** They are not available yet. Use the workarounds below until launch.
{% endhint %}

***

## Planned events

| Event            | When it fires                  |
| ---------------- | ------------------------------ |
| `mail.sent`      | Message handed off to provider |
| `mail.delivered` | Provider confirms delivery     |
| `mail.bounced`   | Hard or soft bounce detected   |
| `mail.failed`    | Send attempt failed            |
| `mail.deferred`  | Queued for next day (quota)    |

Payloads will include `mail_log_id`, `to_email`, `campaign_id`, `status`, and timestamp — signed with HMAC for verification.

***

## Workaround: poll mail logs

Until webhooks ship, query delivery status via API:

```bash
# Recent failures
curl -sS "https://www.mailofly.com/api/v1/mail-logs?status=failed&page_size=50" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Accept: application/json"

# Logs for a specific campaign
curl -sS "https://www.mailofly.com/api/v1/mail-logs?campaign_id=UUID&page_size=100" \
  -H "Authorization: Bearer mf_live_…"
```

Recommended polling interval: **30–60 seconds** during active sends, **5 minutes** otherwise.

***

## Workaround: cron + mail logs

For simple automations, run a scheduled job:

```
Every 5 min → GET /api/v1/mail-logs?status=failed since last check
           → Alert your team / update CRM / retry logic
```

***

## Get notified at launch

Follow the [Mailofly blog](https://www.mailofly.com/blog) or email <support@mailofly.com> to join the webhook beta list.

***

## Related

* [Mail logs](https://docs.mailofly.com/guides/mail-logs)
* [API: Mail logs](https://docs.mailofly.com/api/mail-logs)
* [REST API automation](/external-integrations/automation/rest-api-automation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mailofly.com/external-integrations/automation/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.