Webhooks

Webhooks API manages domain's webhooks. You can create, access and delete webhooks programmatically.

Get domain webhooks

get/v3/domains/{domain}/webhooks

Returns all webhooks for the domain.

SecuritybasicAuth

Request

path Parameters

domain

required

string

Domain name you want webhooks for

Responses

200

A 200 response

Response Schema: application/json

required

object

List of webhooks

	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Accepted webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Delivered webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Opened webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Clicked webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Unsubscribed webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Complained webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Temporary fail webhook URLs
	github.com-mailgun-domains-httpapi-WebhookURLs (object) or null Permanent fail webhook URLs

401

A 401 response

404

A 404 response

Request samples

Response samples

application/json

{"webhooks": {"accepted": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"delivered": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"opened": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"clicked": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"unsubscribed": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"complained": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"temporary_fail": {"urls": ["https://foo.com",
"https://bar.com"
]
},
"permanent_fail": {"urls": ["https://foo.com",
"https://bar.com"
]
}
}
}

Create a domain webhook

post/v3/domains/{domain}/webhooks

Create a list of webhook URLs you'd like to receive Mailgun's POST requests containing event information.

SecuritybasicAuth

Request

path Parameters

domain

required

string

The domain name to create the webhook for

Request Body schema: multipart/form-data
required

id required	string Webhook type to create. Valid types are `accepted`, `clicked`, `opened`, `unsubscribed`, `delivered`, `permanent_fail`, `temporary_fail`, `complained`
url required	string url(s) for webhooks to be sent to. Use multiple times to associate more than one url. Maximum of 3 urls for a given webhook type.

Responses

200

A 200 response

Response Schema: application/json

message required	string A message indicating success
required	object Webhook details

400

A 400 response

401

A 401 response

404

A 404 response

Request samples

Response samples

application/json

{"message": "Webhook has been created",
"webhook": {"urls": ["https://foo.com",
"https://bar.com"
]
}
}

Get domain webhooks by type

get/v3/domains/{domain_name}/webhooks/{webhook_name}

Get the list of url(s) for a webhook identified by its webhook_name.

SecuritybasicAuth

Request

path Parameters

domain_name required	string Domain name you want webhooks for
webhook_name required	string The webhook type you wish to retrieve. Valid types are `accepted`, `clicked`, `opened`, `unsubscribed`, `delivered`, `permanent_fail`, `temporary_fail`, `complained`

Responses

200

A 200 response

Response Schema: application/json

required

object

List of webhooks

urls	Array of strings List of webhooks

401

A 401 response

404

A 404 response

Request samples

Response samples

application/json

{"webhook": {"urls": ["https://foo.com"
]
}
}

Update a domain webhook

put/v3/domains/{domain_name}/webhooks/{webhook_name}

Replace the list of urls by the given one with the url param. Here is the list of supported webhook: accepted, opened, clicked, unsubscribed, delivered, permanent_fail, temporary_fail and complained.

SecuritybasicAuth

Request

path Parameters

domain_name required	string The name of the domain you want to get webhook from
webhook_name required	string The webhook type to update.

Request Body schema: multipart/form-data
required

url

required

string

New url(s) to associate to webhook. Use multiple times to associate more than one url. Maximum of 3 urls for a given type.

Responses

200

A 200 response

Response Schema: application/json

message required	string A message indicating success
required	object Webhook details

400

A 400 response

401

A 401 response

404

A 404 response

Request samples

Response samples

application/json

{"message": "Webhook has been updated",
"webhook": {"urls": ["https://foo.com"
]
}
}

Delete domain webhooks by type

delete/v3/domains/{domain_name}/webhooks/{webhook_name}

Remove all url(s) for a specified webhook type.

SecuritybasicAuth

Request

path Parameters

domain_name required	string The domain name you want to delete the webhook(s) for
webhook_name required	string The name of the webhook to delete. Supported webhook names are `accepted`, `clicked`, `opened`, `unsubscribed`, `delivered`, `permanent_fail`, `temporary_fail`, and `complained`

Responses

200

A 200 response

Response Schema: application/json

message required	string A message indicating success
required	object Webhook details

401

A 401 response

404

A 404 response

Request samples

Response samples

application/json

{"message": "Webhook has been deleted",
"webhook": {"urls": ["https://foo.com"
]
}
}

Cookie Policy GDPR Email Compliance Acceptable Use Policy Terms of Service Privacy Policy

Webhooks

Get domain webhooks

path Parameters

Response Schema: application/json

Create a domain webhook

path Parameters

Request Body schema: multipart/form-datarequired

Response Schema: application/json

Get domain webhooks by type

path Parameters

Response Schema: application/json

Update a domain webhook

path Parameters

Request Body schema: multipart/form-datarequired

Response Schema: application/json

Delete domain webhooks by type

path Parameters

Response Schema: application/json

Request Body schema: multipart/form-data
required

Request Body schema: multipart/form-data
required