The Mailgun API is built on HTTP. Our API is RESTful and it:
Because of this there is no need for developers to learn yet another 3rd party library to use the API. You can use your favorite HTTP/REST library available for your programming language to make HTTP calls to Mailgun. Visit our Wrappers page to see HTTP REST libraries we recommend.
To give you an idea of how to use the API, we have annotated our documentation with code samples written in several popular programming languages. Use the language selector at the top to switch between them.
Our samples from Quickstart Guide, User Manual, API Reference are alive and ready for happy copy&pasting!
All API URLs referenced in this documentation start with the following base part:
https://api.mailgun.net/v2
Your Mailgun account may contain several email domains. To avoid passing the domain name as a query parameter, most API URLs must include the name of the domain you’re interested in:
https://api.mailgun.net/v2/mydomain.com
When you sign up for an account, you are given an API key. You authenticate to the Mailgun API by providing your API key in the request. You can manage your API key in the ‘My Account’ tab of the Control Panel.
Authentication to the API occurs via HTTP Basic Auth. Use api as the user name and your API key is the password. Here is how you use basic HTTP auth with curl:
curl --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0
Or you can try the following API call right your browser:
https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0@api.mailgun.net/v2/samples.mailgun.org/log
Warning
Keep your API key secret!
Mailgun returns JSON for all API calls. JSON does not have a built-in date type, dates are passed as strings encoded according to RFC 2822. This format is native to JavaScript and is also supported by most programming languages out of the box:
'Thu, 13 Oct 2011 18:02:00 GMT'
Mailgun returns standard HTTP response codes.
| Code | Description |
|---|---|
| 200 | Everything worked as expected |
| 400 | Bad Request - Often missing a required parameter |
| 401 | Unauthorized - No valid API key provided |
| 402 | Request Failed - Parameters were valid but request failed |
| 404 | Not Found - The requested item doesn’t exist |
| 500, 502, 503, 504 | Server Errors - something is wrong on Mailgun’s end |