Keys

The Keys API lets you view and manage api keys.

List Mailgun API keys

get/v1/keys

List Mailgun API keys

SecuritybasicAuth
Request
query Parameters
domain_name
string

Domain name filter for domain keys

kind
string

Key kind filter

Enum: "domain" "user" "web"
Responses
200

A 200 response

Response Schema: application/json
total_count
required
integer <int32>
required
Array of objects
400

A 400 response

Request samples 
import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.mailgun.net/v1/keys`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "total_count": 1
}

Create Mailgun API key

post/v1/keys

Create Mailgun API key

SecuritybasicAuth
Request
Request Body schema: multipart/form-data
required
role
required
string

Key role ('admin', 'basic' [use in place of analyst], 'sending' [use with keys of domain kind], 'support', or 'developer')

email
string

API Key user's email address; should be provided for all keys of 'user' & 'web' kinds

domain_name
string

Web domain to associate with the key, for keys of 'domain' kind

kind
string

Type of api key ('domain', 'user', or 'web'). Defaults to 'user' if not provided. Note: web keys are not subject to IP whitelisting and have a default/maximum validity period of 1 day.

expiration
integer

Key lifetime in seconds, must be greater than 0 if set

user_id
string

API Key user's string user ID; should be provided for all keys of 'user' & 'web' kinds

user_name
string

API Key user's name; should be provided for all keys of 'user' kind

description
string

Key description

Responses
200

A 200 response

Response Schema: application/json
message
required
string
required
object
403

A 403 response

Request samples 
import FormData from 'form-data';
import fetch from 'node-fetch';

async function run() {
  const form = new FormData();
  form.append('role','string');

  const resp = await fetch(
    `https://api.mailgun.net/v1/keys`,
    {
      method: 'POST',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      },
      body: form
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "key": {
    • "description": "api key",
    • "kind": "domain",
    • "role": "sending",
    • "created_at": "2006-01-02T15:04:05",
    • "updated_at": "2006-01-02T15:04:05",
    • "domain_name": "example.com",
    • "id": "f2153fd0-f1277777",
    • "user_name": null,
    • "requestor": null
    },
  • "message": "great success"
}

Delete Mailgun API key

delete/v1/keys/{key_id}

Delete Mailgun API key

SecuritybasicAuth
Request
path Parameters
key_id
required
string

The Key ID generated by Mailgun on key creation

Responses
200

A 200 response

Response Schema: application/json
message
required
string
404

A 404 response

Request samples 
import fetch from 'node-fetch';

async function run() {
  const keyId = 'YOUR_key_id_PARAMETER';
  const resp = await fetch(
    `https://api.mailgun.net/v1/keys/${keyId}`,
    {
      method: 'DELETE',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "message": "key deleted"
}

Regenerate Mailgun Public API key

post/v1/keys/public

Regenerate Mailgun Public API key

SecuritybasicAuth
Responses
200

A 200 response

Response Schema: application/json
key
required
string
message
required
string
400

A 400 response

Request samples 
import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.mailgun.net/v1/keys/public`,
    {
      method: 'POST',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "key": "pubkey-626b31f321228ddddddddddcc5a7a1c9",
  • "message": "The public API key has been successfully regenerated."
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.