Mailgun API

api.mailgun.net · Communication

Communication Basic Auth Free Tier Email Transactional Email Communication

Developer-focused transactional email API — send, receive, track, and validate email. Includes email parsing, routing, and suppression management. Free sandbox domain included.

Authentication

Basic authentication HTTP Basic auth with username "api" and your API key from mailgun.com. API key from your Mailgun account settings.

Sample Requests

POST Send an email

Send a test email via Mailgun.

https://api.mailgun.net/v3/YOUR_DOMAIN/messages

Hover any highlighted part to learn what it does

Headers — extra info sent with the request

Content-Type

application/x-www-form-urlencoded

Request Body — data you're sending

"[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun"

curl -X POST "https://api.mailgun.net/v3/YOUR_DOMAIN/messages" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '"[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun"'

import requests
headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic YOUR_BASE64_CREDENTIALS"
}
data = "[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun"
response = requests.post(
    "https://api.mailgun.net/v3/YOUR_DOMAIN/messages",
    headers=headers,
    json=data,
)
print(response.json())

const url = 'https://api.mailgun.net/v3/YOUR_DOMAIN/messages';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic YOUR_BASE64_CREDENTIALS'
  },
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify("[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun"),
}); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"bytes"
	"encoding/json"
)

func main() {
	targetURL := "https://api.mailgun.net/v3/YOUR_DOMAIN/messages"
	jsonData, _ := json.Marshal("[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun")
	req, _ := http.NewRequest("POST", targetURL, bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req.Header.Set("Authorization", "Basic YOUR_BASE64_CREDENTIALS")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://api.mailgun.net/v3/YOUR_DOMAIN/messages")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/x-www-form-urlencoded"
req["Authorization"] = "Basic YOUR_BASE64_CREDENTIALS"
req["Content-Type"] = "application/json"
req.body = "\"[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun\""

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://api.mailgun.net/v3/YOUR_DOMAIN/messages";
$opts = ["http" => [
    "method" => "POST",
    "header" => implode("\r\n", [
        "Content-Type: application/x-www-form-urlencoded",
        "Authorization: Basic YOUR_BASE64_CREDENTIALS",
        "Content-Type: application/json"
    ]),
    "content" => json_encode("[email protected]&[email protected]&subject=Hello&text=Testing+Mailgun"),
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

GET Validate email

Validate an email address.

https://api.mailgun.net/v3/address/validate?address=[email protected]

Hover any highlighted part to learn what it does

Headers — extra info sent with the request

Authorization

Basic YOUR_KEY

curl -X GET "https://api.mailgun.net/v3/address/validate?address=test%40example.com" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS"

import requests
params = {
    "address": "[email protected]"
}
headers = {
    "Authorization": "Basic YOUR_BASE64_CREDENTIALS"
}
response = requests.get(
    "https://api.mailgun.net/v3/address/validate",
    params=params,
    headers=headers,
)
print(response.json())

const url = new URL('https://api.mailgun.net/v3/address/validate');
url.searchParams.set('address', '[email protected]');

const response = await fetch(url, {
  headers: {
    'Authorization': 'Basic YOUR_BASE64_CREDENTIALS'
  },
}); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://api.mailgun.net/v3/address/validate")
	q := baseURL.Query()
	q.Set("address", "[email protected]")
	baseURL.RawQuery = q.Encode()
	targetURL := baseURL.String()
	req, _ := http.NewRequest("GET", targetURL, nil)
	req.Header.Set("Authorization", "Basic YOUR_BASE64_CREDENTIALS")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://api.mailgun.net/v3/address/validate")
uri.query = URI.encode_www_form({
  "address" => "[email protected]"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Basic YOUR_BASE64_CREDENTIALS"

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://api.mailgun.net/v3/address/validate?" . http_build_query([
    "address" => "[email protected]"
]);
$opts = ["http" => [
    "method" => "GET",
    "header" => implode("\r\n", [
        "Authorization: Basic YOUR_BASE64_CREDENTIALS"
    ]),
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

Postman Setup Guide

Get Postman ↗

Sign up at mailgun.com — free sandbox domain included
Get API key from mailgun.com/app/account/security
Use HTTP Basic auth: username="api", password=YOUR_API_KEY
Sandbox: use sandbox domain for testing (authorized recipients only)
Add your email as authorized recipient in sandbox settings

What can you build with Mailgun API?

Mailgun API is a Communication API. Developers commonly use communication APIs for:

sending SMS alerts and notifications
building in-app chat and messaging features
automating email sequences and transactional emails
creating voice bots and IVR systems
verifying phone numbers at signup

Basic authentication. Send your username and password (Base64-encoded) in the Authorization header. Always use HTTPS — Basic auth over plain HTTP exposes your credentials. Mailgun API is free to use up to a usage limit, making it a low-risk choice to experiment with.

New to APIs? Read our beginner's guide

Open documentation ↗