API version 1

API reference.

Authentication, developer domains, inboxes, messages, webhooks, errors, and SDK examples.

Authentication: Authorization: Bearer md_test_…. Keep the key in a secret manager. The complete value is shown only once.

Complete API reference

Base URL: https://api.maildrop.online/v1

Scope	Purpose
`inboxes:read`	Read inboxes
`inboxes:write`	Create/delete inboxes
`messages:read`	Read messages and OTP metadata
`webhooks:write`	Manage webhook endpoints

GET/accountAny valid API key

Return the organization, active subscription, and granted scopes.

curl -X GET "https://api.maildrop.online/v1/account" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/account", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/account",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/account"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/limitsusage:read

Return effective plan limits and account overrides.

curl -X GET "https://api.maildrop.online/v1/limits" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/limits", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/limits",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/limits"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/usageusage:read

Return current-month usage.

curl -X GET "https://api.maildrop.online/v1/usage" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/usage"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/domainsinboxes:read

List developer inbox domains enabled for the active plan.

curl -X GET "https://api.maildrop.online/v1/domains" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/domains", { headers: { Authorization: `Bearer ${process.env.MAILDROP_API_KEY}` } });
console.log(await response.json());

import os, requests
response = requests.get("https://api.maildrop.online/v1/domains", headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"}, timeout=20)
response.raise_for_status()
print(response.json())

using var domains = await client.ListDomainsAsync();
Console.WriteLine(domains.RootElement);

GET/inboxes?limit=100inboxes:read

List private inboxes owned by the workspace.

curl -X GET "https://api.maildrop.online/v1/inboxes?limit=100" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes?limit=100", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes?limit=100",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes?limit=100"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/inboxesinboxes:write

Create a private inbox. Use an Idempotency-Key for safe retries.

curl -X POST "https://api.maildrop.online/v1/inboxes" \
  -H "Authorization: Bearer $MAILDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-001" \
  -d '{"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24}'

const response = await fetch("https://api.maildrop.online/v1/inboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",\n    "Idempotency-Key": crypto.randomUUID()
  },\n  body: JSON.stringify({"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24})
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    json={"local":"checkout-qa","domain":"tests.maildrop.online","lifetime_hours":24},
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.PostAsJsonAsync("https://api.maildrop.online/v1/inboxes", new { local = "checkout-qa", domain = "tests.maildrop.online", lifetime_hours = 24 });
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/inboxes/{inbox_id}inboxes:read

Get one private inbox.

curl -X GET "https://api.maildrop.online/v1/inboxes/123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes/123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes/123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/inboxes/{inbox_id}inboxes:write

Soft-delete a private inbox.

curl -X DELETE "https://api.maildrop.online/v1/inboxes/123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/inboxes/123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/inboxes/123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/inboxes/{inbox_id}/messages?limit=100&after_id=0messages:read

List stored messages and OTP summaries.

curl -X GET "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/inboxes/123/messages?limit=100&after_id=0"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/messages/{message_id}messages:read

Get the full message and OTP metadata.

curl -X GET "https://api.maildrop.online/v1/messages/456" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/messages/456",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/messages/456"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/messages/{message_id}messages:delete

Soft-delete one message.

curl -X DELETE "https://api.maildrop.online/v1/messages/456" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/messages/456",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/messages/456"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/messages/{message_id}/attachmentsattachments:read

List attachment metadata. Byte download requires R2 storage.

curl -X GET "https://api.maildrop.online/v1/messages/456/attachments" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/messages/456/attachments", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/messages/456/attachments",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/messages/456/attachments"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET/webhookswebhooks:read

List signed webhook endpoints.

curl -X GET "https://api.maildrop.online/v1/webhooks" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "GET",
    "https://api.maildrop.online/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "https://api.maildrop.online/v1/webhooks"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/webhookswebhooks:write

Create a webhook endpoint; the signing secret is returned once.

curl -X POST "https://api.maildrop.online/v1/webhooks" \
  -H "Authorization: Bearer $MAILDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-001" \
  -d '{"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]}'

const response = await fetch("https://api.maildrop.online/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",\n    "Idempotency-Key": crypto.randomUUID()
  },\n  body: JSON.stringify({"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]})
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    json={"name":"CI receiver","url":"https://example.com/maildrop-events","events":["message.received"]},
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Post, "https://api.maildrop.online/v1/webhooks"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

PATCH/webhooks/{webhook_id}webhooks:write

Update URL, events, name, or status.

curl -X PATCH "https://api.maildrop.online/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "PATCH",
    "https://api.maildrop.online/v1/webhooks/wh_123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Patch, "https://api.maildrop.online/v1/webhooks/wh_123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE/webhooks/{webhook_id}webhooks:write

Delete a webhook endpoint.

curl -X DELETE "https://api.maildrop.online/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "DELETE",
    "https://api.maildrop.online/v1/webhooks/wh_123",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Delete, "https://api.maildrop.online/v1/webhooks/wh_123"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST/webhooks/{webhook_id}/testwebhooks:write

Send a signed test event.

curl -X POST "https://api.maildrop.online/v1/webhooks/wh_123/test" \
  -H "Authorization: Bearer $MAILDROP_API_KEY"

const response = await fetch("https://api.maildrop.online/v1/webhooks/wh_123/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILDROP_API_KEY}`,
    Accept: "application/json"
    
  }
});
console.log(await response.json());

import os, requests
response = requests.request(
    "POST",
    "https://api.maildrop.online/v1/webhooks/wh_123/test",
    headers={"Authorization": f"Bearer {os.environ['MAILDROP_API_KEY']}"},
    
    timeout=20,
)
response.raise_for_status()
print(response.json())

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MAILDROP_API_KEY"));
var response = await http.SendAsync(new HttpRequestMessage(HttpMethod.Post, "https://api.maildrop.online/v1/webhooks/wh_123/test"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Structured errors

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Missing messages:read scope.",
    "request_id": "cf-ray-or-uuid",
    "details": {}
  }
}

Common statuses: 400, 401, 403, 404, 409, 429, and 500.

Webhook signature verification

Compute HMAC-SHA256 over the timestamp, a dot, and the exact raw request body.

signed = timestamp + "." + raw_request_body
signature = HMAC_SHA256(signing_secret, signed)
X-MailDrop-Signature: t=TIMESTAMP,v1=HEX_SIGNATURE

Team governance and member policy

Owners and workspace administrators can invite members, assign roles, choose personal/shared resource behavior, and set per-member permissions and caps. Member caps can reduce but never exceed plan limits.

GET/teamteam:read

POST/team/invitationsteam:write

PATCH/team/members/{user_id}team:write

{
  "action": "policy",
  "role": "developer",
  "resource_mode": "shared",
  "permissions": { "inboxes.shared.read": true, "api_keys.create": true },
  "limits": { "max_active_inboxes": 10, "max_api_keys": 2 }
}