1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <meta charset="UTF-8"> 5 <title>IsTempMail API Documentation</title> 6 7 <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> 8 <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"> 9 <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"> 10 <link rel="manifest" href="/site.webmanifest"> 11 12 <meta name="viewport" content="width=device-width, initial-scale=1"> 13 14 <meta name="description" content="HTTP API to detect disposable, temporary and unresolvable email addresses. Endpoints, authentication, rate limits, response formats and integration examples."> 15 <meta name="keywords" content="IsTempMail, API, documentation, disposable email, temporary email, email verification"> 16 <style> 17.docs-title-strip { 18 position: sticky; 19 top: 64px; /* below the navbar */ 20 z-index: 1010; 21} 22 23.docs-toc { 24 position: sticky; 25 top: 10rem; 26 max-height: calc(100vh - 11rem); 27 overflow-y: auto; 28} 29.docs-toc > ul > li > a { font-weight: 600; color: #212529; } 30.docs-toc ul ul a { font-weight: 400; color: #495057; } 31.docs-toc a:hover { color: #1d4ed8; } 32 33.docs-content section, 34.docs-content :is(h2, h3, h4, h5)[id] { scroll-margin-top: 10rem; } 35.docs-content > section + section { margin-top: 4rem; } 36.docs-content h2 { margin-bottom: 1.25rem; } 37.docs-content h3 { margin-top: 2.5rem; margin-bottom: 1rem; } 38.docs-content h5 { margin-top: 2rem !important; margin-bottom: 0.5rem; } 39 40.docs-content pre[class*="language-"] { position: relative; } 41.docs-content .copy-btn { 42 position: absolute; 43 top: 0.4rem; 44 right: 0.4rem; 45 padding: 0.15rem 0.55rem; 46 font-size: 0.7rem; 47 font-family: inherit; 48 color: #ccc; 49 background: rgba(255,255,255,0.08); 50 border: 1px solid rgba(255,255,255,0.18); 51 border-radius: 3px; 52 cursor: pointer; 53 transition: color 0.12s, background 0.12s, border-color 0.12s; 54} 55.docs-content .copy-btn:hover { background: rgba(255,255,255,0.18); color: #fff; } 56.docs-content .copy-btn.copied { color: #8fd14f; border-color: #8fd14f; } 57</style> 58 59 <link rel="stylesheet" href="/build/184.eb7d897b.css">
59<script src="/build/runtime.16bb7e4e.js" defer></script>
59<script src="/build/951.3677c5be.js" defer></script>
59<script src="/build/603.4ea35443.js" defer></script>
59<script src="/build/434.4b9d8d80.js" defer></script>
59<script src="/build/app.0397aea4.js" defer></script>
59<script src="/build/848.6b66e12d.js" defer></script>
59<script src="/build/387.85b03fbe.js" defer></script>
59<script src="/build/prism.ccefb95e.js" defer></script>
59 60
60<script src="https://kit.fontawesome.com/7a0432061b.js" crossorigin="anonymous" defer></script>
60 61 62 <link rel="canonical" href="https://www.istempmail.com/docs/api" /> 63 64</head> 65<body> 66<nav class="navbar navbar-expand-lg itm-navbar mb-0 sticky-top"> 67 <div class="container"> 68 <a class="navbar-brand itm-color-accent me-5" href="/"> 69 <img src="/build/images/[email protected]" alt="IsTempMail" width="180" height="28" class="inline-block"> 70 <span class="d-none">IsTempMail</span></a> 71 <button class="navbar-toggler" type="button" data-bs-toggle="collapse" 72 data-bs-target="#navbarSupportedContent" 73 aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation"> 74 <span class="navbar-toggler-icon"></span> 75 </button> 76 <div class="collapse navbar-collapse" id="navbarSupportedContent"> 77 <ul class="navbar-nav me-auto mb-2 mb-lg-0"> 78 <li class="nav-item"> 79 <a class="nav-link" href="/#benefits">Benefits</a> 80 </li> 81 <li class="nav-item"> 82 <a class="nav-link" href="/#api">API</a> 83 </li> 84 <li class="nav-item"> 85 <a class="nav-link" href="/#wordpress-plugin">WordPress Plugin</a> 86 </li> 87 <li class="nav-item"> 88 <a class="nav-link" href="/#pricing">Pricing</a> 89 </li> 90 <li class="nav-item"> 91 <a class="nav-link" href="/docs/api">Docs</a> 92 </li> 93 </ul> 94 <ul class="navbar-nav d-lg-flex flex-lg-row align-items-lg-center"> 95 <li class="nav-item"> 96 <a href="/login" class="nav-link">Login</a> 97 </li> 98 <li class="nav-item ms-lg-3 mt-lg-0 mt-3"> 99 <a href="/sign-up" class="btn btn-primary">Get started</a> 100 </li> 101 </ul> 102 </div> 103 </div> 104</nav> 105<div class="bg-gradient mt-0 mb-0 py-3 border-bottom mb-3 docs-title-strip" style="background-color: #f1f1f1"> 106 <div class="container"> 107 <h1 class="lead fs-3 mb-0">API Documentation</h1> 108 </div> 109</div> 110 111<div class="container mb-5"> 112 <div class="row"> 113 <aside class="col-lg-3 col-md-4 mb-4"> 114 <nav class="docs-toc"> 115 <ul class="list-unstyled small mb-0"> 116 <li class="mb-1"><a href="#overview" class="text-decoration-none">Overview</a></li> 117 <li class="mb-1"><a href="#quickstart" class="text-decoration-none">Quick Start</a></li> 118 <li class="mb-1"><a href="#authentication" class="text-decoration-none">Authentication</a></li> 119 <li class="mb-1"> 120 <a href="#endpoints" class="text-decoration-none">Endpoints</a> 121 <ul class="list-unstyled ps-3 mt-1"> 122 <li><a href="#endpoint-check" class="text-decoration-none">Check</a></li> 123 <li><a href="#endpoint-block" class="text-decoration-none">Block list</a></li> 124 <li><a href="#endpoint-allow" class="text-decoration-none">Allow list</a></li> 125 <li><a href="#endpoint-report" class="text-decoration-none">Report</a></li> 126 </ul> 127 </li> 128 <li class="mb-1"><a href="#response-formats" class="text-decoration-none">Response Formats</a></li> 129 <li class="mb-1"><a href="#rate-limits" class="text-decoration-none">Rate Limits & Quotas</a></li> 130 <li class="mb-1"> 131 <a href="#sample-code" class="text-decoration-none">Sample Code</a> 132 <ul class="list-unstyled ps-3 mt-1"> 133 <li><a href="#example-curl" class="text-decoration-none">cURL</a></li> 134 <li><a href="#example-node" class="text-decoration-none">Node.js</a></li> 135 <li><a href="#example-nextjs" class="text-decoration-none">Next.js</a></li> 136 <li><a href="#example-python" class="text-decoration-none">Python</a></li> 137 <li><a href="#example-ruby" class="text-decoration-none">Ruby</a></li> 138 <li><a href="#example-go" class="text-decoration-none">Go</a></li> 139 <li><a href="#example-php" class="text-decoration-none">PHP</a></li> 140 <li><a href="#example-java" class="text-decoration-none">Java</a></li> 141 <li><a href="#example-csharp" class="text-decoration-none">C# / .NET</a></li> 142 <li><a href="#example-rust" class="text-decoration-none">Rust</a></li> 143 <li><a href="#example-cloudflare" class="text-decoration-none">Cloudflare Worker</a></li> 144 <li><a href="#example-express" class="text-decoration-none">Express</a></li> 145 <li><a href="#example-wordpress" class="text-decoration-none">WordPress</a></li> 146 </ul> 147 </li> 148 <li class="mb-1"><a href="#faq" class="text-decoration-none">FAQ</a></li> 149 </ul> 150 </nav> 151 </aside> 152 153 <main class="col-lg-9 col-md-8 docs-content"> 154 <p class="text-muted small mb-4">Last updated 2026-04-27</p> 155 156 <section id="overview" class="mb-5"> 157 <h2>Overview</h2> 158 <p> 159 IsTempMail is a real-time HTTP API that verifies whether an email address or domain 160 is disposable, temporary, or otherwise unresolvable. It is built for sign-up forms, 161 lead capture, payment flows, and anywhere you accept an email address from a user. 162 </p> 163 164 <h4 class="mt-4">What it does</h4> 165 <ul> 166 <li>Checks any email or domain against a curated block list of 130k+ disposable providers, updated multiple times daily.</li> 167 <li>Detects domains that don’t resolve (typos, dead MX records).</li> 168 <li>Lets you maintain your own per-account block list and allow list (paid plans).</li> 169 <li>Lets you report suspicious domains for review.</li> 170 </ul> 171 172 173 <h4 class="mt-4">Base URL</h4> 174<pre class="language-bash"><code class="language-bash">https://www.istempmail.com/api</code></pre> 175 <p>All endpoint paths below are relative to this base URL. Responses are JSON.</p> 176 </section> 177 178 <section id="quickstart" class="mb-5"> 179 <h2>Quick Start</h2> 180 181 <p><strong>1. Get your API token</strong></p> 182 <p><a href="/sign-up">Sign up</a>, then copy your 32-character API token from the dashboard. The free plan gives you 200 checks/month — enough to integrate and test.</p> 183 184 <p><strong>2. Make your first request</strong></p> 185<pre class="language-bash"><code class="language-bash">curl "https://www.istempmail.com/api/check/YOUR_TOKEN/mailinator.com"</code></pre> 186 187 <p>Response:</p> 188<pre class="language-json"><code class="language-json">{
189 "name": "mailinator.com", 190 "blocked": true 191}</code></pre> 192 193 <p><code>blocked: true</code> means the domain is on the disposable list. Reject the sign-up, ask for another address, or flag the user for review — your call.</p> 194 195 <p><strong>3. Check an email address (not just a domain)</strong></p> 196<pre class="language-bash"><code class="language-bash">curl "https://www.istempmail.com/api/check/YOUR_TOKEN/[email protected]"</code></pre> 197 198 <p>The API extracts and normalises the domain for you. Response:</p> 199<pre class="language-json"><code class="language-json">{ 200 "name": "gmail.com", 201 "blocked": false 202}</code></pre> 203 204 <p>That’s the whole API for the common case. Everything below is for managing your custom lists and integrating cleanly into production.</p> 205 </section> 206 207 <section id="authentication" class="mb-5"> 208 <h2>Authentication</h2> 209 <p>All endpoints require your 32-character API token. Two authentication methods are supported:</p> 210 211 <div class="table-responsive"> 212 <table class="table table-bordered"> 213 <thead> 214 <tr> 215 <th>Method</th> 216 <th>Where the token goes</th> 217 <th>Works with</th> 218 </tr> 219 </thead> 220 <tbody> 221 <tr> 222 <td><strong>Bearer token</strong></td> 223 <td><code>Authorization: Bearer {token}</code> header</td> 224 <td>All endpoints</td> 225 </tr> 226 <tr> 227 <td><strong>Path token</strong></td> 228 <td>In the URL: <code>/check/{token}/{name}</code></td> 229 <td><code>/check</code> only — quick alternative for one-line cURL or copy-paste testing, no headers required</td> 230 </tr> 231 </tbody> 232 </table> 233 </div> 234 235 <p>Both methods accept the same token value and reach the same result. Treat the token as a
235secret — anyone with it can consume your quota and modify your custom lists. Rotate it from the dashboard if it leaks.</p> 236 237 <div class="alert alert-warning"> 238 <strong>⚠ Don’t put path-token URLs in client-side JavaScript or mobile apps</strong> where users can read them. For browser/mobile use, proxy the call through your backend. 239 </div> 240 </section> 241 242 <section id="endpoints" class="mb-5"> 243 <h2>Endpoints</h2> 244 245 <h3 id="endpoint-check" class="mt-4">Check a domain or email</h3> 246 <p>Returns the block status of a domain. If you pass an email, the local-part is stripped and only the domain is checked.</p> 247<pre class="language-bash"><code class="language-bash">curl "https://www.istempmail.com/api/check/mailinator.com" \ 248 -H "Authorization: Bearer $ITM_TOKEN"</code></pre> 249 <p class="small text-muted mt-1"> 250 See sample code: 251 <a href="#example-node">Node.js</a> · 252 <a href="#example-nextjs">Next.js</a> · 253 <a href="#example-python">Python</a> · 254 <a href="#example-ruby">Ruby</a> · 255 <a href="#example-go">Go</a> · 256 <a href="#example-php">PHP</a> · 257 <a href="#example-cloudflare">Cloudflare Worker</a> · 258 <a href="#example-express">Express</a> 259 </p> 260 261 <p class="mt-3"><strong>Quick alternative</strong> — same endpoint, token in the path, no headers needed:</p> 262<pre class="language-bash"><code class="language-bash">curl "https://www.istempmail.com/api/check/YOUR_TOKEN/mailinator.com"</code></pre> 263 264 <h5>Parameters</h5> 265 <div class="table-responsive"> 266 <table class="table table-sm table-bordered"> 267 <thead> 268 <tr><th>Name</th><th>Required</th><th>Description</th></tr> 269 </thead> 270 <tbody> 271 <tr><td><code>name</code></td><td>yes</td><td>A domain (<code>example.com</code>) or full email (<code>[email protected]</code>)</td></tr> 272 <tr><td><code>token</code></td><td>yes</td><td>Your 32-character API token. Pass via <code>Authorization: Bearer</code> header, or in the URL path as shown above.</td></tr> 273 </tbody> 274 </table> 275 </div> 276 277 <h5>Response 200</h5> 278<pre class="language-json"><code class="language-json">{
279 "name": "example.com", 280 "blocked": false, 281 "unresolvable": true 282}</code></pre> 283 284 <div class="table-responsive"> 285 <table class="table table-sm table-bordered"> 286 <thead> 287 <tr><th>Field</th><th>Type</th><th>Description</th></tr> 288 </thead> 289 <tbody> 290 <tr><td><code>name</code></td><td>string</td><td>The normalised domain that was checked (lowercase)</td></tr> 291 <tr><td><code>blocked</code></td><td>boolean</td><td><code>true</code> if the domain is on the global or your custom block list</td></tr> 292 <tr><td><code>unresolvable</code></td><td>boolean</td><td><em>Optional.</em> Present and <code>true</code> only when the domain has no MX records (e.g. typo, dead domain). Treat as a soft signal — fine for warning, not always for hard-blocking</td></tr> 293 </tbody> 294 </table> 295 </div> 296 297 <p><code>blocked</code> reflects your effective view: your allow list overrides the global block list, and your block list adds to it.</p> 298 299 <h3 id="endpoint-block" class="mt-5">Add a domain to your block list</h3> 300 <p>Available on <strong>Standard plan and above.</strong> Adds a domain to your account’s custom block list, so future <code>/check</code> calls return <code>blocked: true</code> for that domain even if it isn’t on the global list.</p> 301<pre class="language-bash"><code class="language-bash">curl -X POST "https://www.istempmail.com/api/block" \ 302 -H "Authorization: Bearer $ITM_TOKEN" \ 303 -H "Content-Type: application/json" \ 304 -d '{"domain":"spam-domain.example","comment":"Reported by support 2026-04-21"}'</code></pre> 305 <p class="small text-muted mt-1"> 306 See sample code: 307 <a href="#example-node">Node.js</a> · 308 <a href="#example-python">Python</a> · 309 <a href="#example-ruby">Ruby</a> · 310 <a href="#example-go">Go</a> · 311 <a href="#example-php">PHP</a> 312 </p> 313 314 <h5>Body</h5> 315<pre class="language-json"><code class="language-json">{ 316 "domain": "spam-domain.example", 317 "comment": "Reported by support 2026-04-21" 318}</code></pre> 319 320 <div class="table-responsive"> 321 <table class="table table-sm table-bordered"> 322 <thead> 323 <tr><th>Field</th><th>Required</th><th>Notes</th></tr> 324 </thead> 325 <tbody> 326 <tr><td><code>domain</code></td><td>yes</td><td>The domain to block</td></tr> 327 <tr><td><code>comment</code></td><td>no</td><td>Free-text note shown in your dashboard. Max 255 chars</td></tr> 328 </tbody> 329 </table> 330 </div> 331 332 <h5>Response 200</h5> 333<pre class="language-json"><code class="language-json">{ 334 "success": true, 335 "message": "Domain spam-domain.example was added to your block list." 336}</code></pre> 337 338 <p>If the domain is already on the <strong>global</strong> block list, the response is still <code>success: true</code> but explains it wasn’t added to your custom list (no need — it’s already blocked for you).</p> 339 340 <div class="alert alert-info small"> 341 <strong>Note:</strong> Custom-list entries are removed when a domain is added to the global block list. This keeps your list focused on entries the global list doesn’t cover. 342 </div> 343 344 <h3 id="endpoint-allow" class="mt-5">Add a domain to your allow list</h3> 345 <p>Available on <strong>Standard plan and above.</strong> Forces a domain to return <code>blocked: false</code> for your account, even if it appears on the global block list.</p> 346<pre class="language-bash"><code class="language-bash">curl -X POST "https://www.istempmail.com/api/allow" \ 347 -H "Authorization: Bearer $ITM_TOKEN" \ 348 -H "Content-Type: application/json" \ 349 -d '{"domain":"partner.example"}'</code></pre> 350 <p class="small text-muted mt-1"> 351 See sample code: 352 <a href="#example-node">Node.js</a> · 353 <a href="#example-python">Python</a> · 354 <a href="#example-ruby">Ruby</a> · 355 <a href="#example-go">Go</a> · 356 <a href="#example-php">PHP</a> 357 </p> 358 359 <p>
359Body, comment rules, and response shape are identical to <code>/block</code>.</p> 360 361 <h5>Response 200</h5> 362<pre class="language-json"><code class="language-json">{ 363 "success": true, 364 "message": "The domain partner.example was added to your allow list." 365}</code></pre> 366 367 <p>If the domain is already on the <strong>global</strong> allow list, the response is still <code>success: true</code> but explains it wasn’t added to your custom list (no need — it’s already allowed for you).</p> 368 369 <h3 id="endpoint-report" class="mt-5">Report a suspicious domain</h3> 370 <p>Submit a domain for review by the IsTempMail team. Available on <strong>all plans, including free.</strong> Use this when you spot a disposable provider that isn’t on the global block list yet.</p> 371<pre class="language-bash"><code class="language-bash">curl -X POST "https://www.istempmail.com/api/report" \ 372 -H "Authorization: Bearer $ITM_TOKEN" \ 373 -H "Content-Type: application/json" \ 374 -d '{"domain":"new-temp-mail.example","comment":"Hit our signup form 50 times in 1 hour"}'</code></pre> 375 <p class="small text-muted mt-1"> 376 See sample code: 377 <a href="#example-node">Node.js</a> · 378 <a href="#example-python">Python</a> · 379 <a href="#example-ruby">Ruby</a> · 380 <a href="#example-go">Go</a> · 381 <a href="#example-php">PHP</a> 382 </p> 383 384 <h5>Body</h5> 385<pre class="language-json"><code class="language-json">{ 386 "domain": "new-temp-mail.example", 387 "comment": "Hit our signup form 50 times in 1 hour" 388}</code></pre> 389 390 <h5>Response 200</h5> 391<pre class="language-json"><code class="language-json">{ 392 "success": true, 393 "message": "Thank you for reporting new-temp-mail.example. It will be reviewed by our team and blocked if necessary." 394}</code></pre> 395 396 <p>If the domain has already been reviewed, you’ll get a <code>global_allowlist</code> or <code>global_blocklist</code> response so you can decide whether to add it to your custom list anyway.</p> 397 398 <div class="alert alert-info"> 399 <strong>What happens next</strong> 400 <ol class="mb-0 mt-2"> 401 <li><strong>Manual review.</strong> A member of the IsTempMail team examines the domain — MX records, registration patterns, provider signals, and the context you supplied in <code>comment</code>.</li> 402 <li><strong>Block or allow decision.</strong> The domain is added to the global block list (if confirmed disposable) or the global allow list (if it’s a legitimate provider).</li> 403 <li><strong>Email notification.</strong> You receive an email at the address on your account with the final decision and a short rationale.</li> 404 </ol> 405 </div> 406 </section> 407 408 <section id="response-formats" class="mb-5"> 409 <h2>Response Formats</h2> 410 411 <h5>Success (check)</h5> 412<pre class="language-json"><code class="language-json">{ "name": "example.com", "blocked": false }</code></pre> 413 414 <h5>Success (block / allow / report)</h5> 415<pre class="language-json"><code class="language-json">{ "success": true, "message": "..." }</code></pre> 416 417 <h5>Errors</h5> 418 <p>All errors follow the same shape:</p> 419<pre class="language-json"><code class="language-json">{ 420 "success": false, 421 "error": "error_code", 422 "error_description": "Human-readable explanation." 423}</code></pre> 424 425 <p>Legacy check errors omit the <code>success</code> field but carry the same <code>error</code> and <code>error_description</code>.</p> 426 427 <div class="table-responsive"> 428 <table class="table table-bordered"> 429 <thead> 430 <tr><th>HTTP</th><th>When</th></tr> 431 </thead> 432 <tbody> 433 <tr><td><code>400</code></td><td>Malformed JSON, missing/invalid <code>domain</code> field, comment over 255 chars</td></tr> 434 <tr><td><code>401</code></td><td>Missing <code>Authorization</code> header, invalid token</td></tr> 435 <tr><td><code>403</code></td><td>Plan restriction (custom lists not on your plan), expired account, negative balance</td></tr> 436 <tr><td><code>429</code></td><td>Monthly request quota exceeded</td></tr> 437 <tr><td><code>500</code></td><td>Server error — retry with exponential backoff</td></tr> 438 </tbody> 439 </table> 440 </div> 441 442 <h5>Common error codes</h5> 443 <div class="table-responsive"> 444 <table class="table table-bordered"> 445 <thead> 446 <tr><th>Code</th><th>When</th></tr> 447 </thead> 448 <tbody> 449 <tr><td><code>app_error</code></td><td>Generic, see <code>error_description</code></td></tr> 450 <tr><td><code>unauthorized</code></td><td>Auth failed</td></tr> 451 <tr><td><code>plan_restriction</code></td><td>Endpoint requires a higher plan</td></tr> 452 <tr><td><code>global_allowlist</code></td><td>Reported domain already on global allow list (returned by <code>/report</code>)</td></tr> 453 <tr><td><code>global_blocklist</code></td><td>Reported domain already on global block list (returned by <code>/report</code>)</td></tr> 454 </tbody> 455 </table> 456 </div> 457 </section> 458 459 <section id="rate-limits" class="mb-5"> 460 <h2>Rate Limits & Quotas</h2> 461 <p> 462 Quotas are measured as <strong>
462total requests over a rolling 30-day window</strong>, not per minute or per day. 463 There are no burst limits — make calls as fast as you want, as long as the rolling total stays under your plan limit. 464 <strong>Every API call counts</strong> against your quota, including repeated checks of the same domain — there is no server-side deduplication. 465 </p> 466 467 <div class="table-responsive"> 468 <table class="table table-bordered"> 469 <thead> 470 <tr><th>Plan</th><th>Requests / 30 days</th><th>Custom block & allow list</th></tr> 471 </thead> 472 <tbody> 473 <tr><td>Free</td><td>200</td><td>—</td></tr> 474 <tr><td>Standard</td><td>5,000</td><td>✓</td></tr> 475 <tr><td>Plus</td><td>15,000</td><td>✓</td></tr> 476 <tr><td>Pro</td><td>50,000</td><td>✓</td></tr> 477 <tr><td>Max</td><td>Unlimited</td><td>✓</td></tr> 478 </tbody> 479 </table> 480 </div> 481 482 <p>When you exceed your quota:</p> 483 <ul> 484 <li>The API returns <code>429 Too Many Requests</code>.</li> 485 <li>We send you a notification email (at most once per day, not per request).</li> 486 <li>The limit takes effect immediately. Upgrade your plan to restore service.</li> 487 </ul> 488 489 <p>If you anticipate a spike (a launch, a campaign), upgrade in advance — overage is not billed automatically except on the Max plan.</p> 490 </section> 491 492 <section id="sample-code" class="mb-5"> 493 <h2>Sample Code</h2> 494 495 <p>Pick a language, copy the <strong>Setup</strong> snippet once, then drop in only the endpoint snippets you actually need (<strong>Check</strong>, <strong>Block</strong>, <strong>Allow</strong>, <strong>Report</strong>). All examples assume your token is in the <code>ITM_TOKEN</code> environment variable — never hard-code it.</p> 496 497 <h3 id="example-curl" class="mt-5">cURL</h3> 498 <p class="text-muted small">Bare HTTP requests from your terminal — ideal for testing, debugging, and ad-hoc shell pipelines.</p> 499 500 <h5 id="example-curl-setup" class="mt-3">Setup</h5> 501<pre class="language-bash"><code class="language-bash">export BASE_URL="https://www.istempmail.com/api" 502export ITM_TOKEN="your_32_character_api_token" 503AUTH=(-H "Authorization: Bearer $ITM_TOKEN") 504JSON=(-H "Content-Type: application/json")</code></pre> 505 506 <h5 id="example-curl-check" class="mt-3">Check</h5> 507<pre class="language-bash"><code class="language-bash">curl "$BASE_URL/check/mailinator.com" "${AUTH[@]}"</code></pre> 508 509 <h5 id="example-curl-block" class="mt-3">Block</h5> 510<pre class="language-bash"><code class="language-bash">curl -X POST "$BASE_URL/block" "${AUTH[@]}" "${JSON[@]}" \ 511 -d '{"domain":"spam-domain.example","comment":"Repeated abuse"}'</code></pre> 512 513 <h5 id="example-curl-allow" class="mt-3">Allow</h5> 514<pre class="language-bash"><code class="language-bash">curl -X POST "$BASE_URL/allow" "${AUTH[@]}" "${JSON[@]}" \ 515 -d '{"domain":"partner.example"}'</code></pre> 516 517 <h5 id="example-curl-report" class="mt-3">Report</h5> 518<pre class="language-bash"><code class="language-bash">curl -X POST "$BASE_URL/report" "${AUTH[@]}" "${JSON[@]}" \ 519 -d '{"domain":"new-temp-mail.example"}'</code></pre> 520 521 <h3 id="example-node" class="mt-5">Node.js (native fetch, Node 18+)</h3> 522 <p class="text-muted small">Plain <code>fetch</code> against the API — works in any backend Node runtime (Express, Fastify, Hono, NestJS).</p> 523 524 <h5 id="example-node-setup" class="mt-3">Setup</h5> 525<pre class="language-javascript"><code class="language-javascript">const BASE_URL = 'https://www.istempmail.com/api'; 526const headers = { 527 Authorization: `Bearer ${process.env.ITM_TOKEN}`, 528 'Content-Type': 'application/json', 529};</code></pre> 530 531 <h5 id="example-node-check" class="mt-3">Check</h5> 532<pre class="language-javascript"><code class="language-javascript">const email = '[email protected]'; 533const res = await fetch(`${BASE_URL}/check/${encodeURIComponent(email)}`, { headers }); 534const data = await res.json(); 535if (data.blocked) throw new Error('Disposable email');</code></pre> 536 537 <h5 id="example-node-block" class="mt-3">Block</h5> 538<pre class="language-javascript"><code class="language-javascript">await fetch(`${BASE_URL}/block`, { 539 method: 'POST', 540 headers, 541 body: JSON.stringify({ domain: 'spam-domain.example', comment: 'Repeated abuse' }), 542});</code></pre> 543 544 <h5 id="example-node-allow" class="mt-3">Allow</h5> 545<pre class="language-javascript"><code class="language-javascript">await fetch(`${BASE_URL}/allow`, { 546 method: 'POST', 547 headers, 548 body: JSON.stringify({ domain: 'partner.example' }), 549});</code></pre> 550 551 <h5 id="example-node-report" class="mt-3">Report</h5> 552<pre class="language-javascript"><code class="language-javascript">await fetch(`${BASE_URL}/report`, { 553 method: 'POST', 554 headers, 555 body: JSON.stringify({ domain: 'new-temp-mail.example' }), 556});</code></pre> 557 558 <h3 id="example-nextjs" class="mt-5">Next.js Server Action (TypeScript)</h3> 559 <p class="text-muted small">App Router pattern — type-safe wrappers you import from your form actions. Token never reaches the client.</p> 560 561 <h5 id="example-nextjs-setup" class="mt-3">Setup</h5> 562<pre class="language-typescript"><code class="language-typescript">'use server'; 563 564const BASE_URL = 'https://www.istempmail.com/api'; 565const headers = () => ({ 566 Authorization: `Bearer ${process.env.ITM_TOKEN!}`, 567 'Content-Type': 'application/json', 568});</code></pre> 569 570 <h5 id="example-nextjs-check" class="mt-3">Check</h5> 571<pre class="language-typescript"><code class="language-typescript">type CheckResponse = { name: string; blocked: boolean; unresolvable?: boolean }; 572 573export async function validateEmail(email: string) { 574 const res = await fetch(`${BASE_URL}/check/${encodeURIComponent(email)}`, { 575 headers: headers(), 576 cache: 'no-store', 577 }); 578 const data = (await res.json()) as CheckResponse; 579 if (data.blocked) return { ok: false, reason: 'Please use a permanent email address.' }; 580 if (data.unresolvable) return { ok: false, reason: "That domain doesn't look right â typo?" }; 581 return { ok: true }; 582}</code></pre> 583 584 <h5 id="example-nextjs-block" class="mt-3">Block</h5> 585<pre class="language-typescript"><code class="language-typescript">export async function blockDomain(domain: string, comment?: string) { 586 await fetch(`${BASE_URL}/block`, { 587 method: 'POST', 588 headers: headers(), 589 body: JSON.stringify({ domain, comment }), 590 }); 591}</code></pre> 592 593 <h5 id="example-nextjs-allow" class="mt-3">Allow</h5> 594<pre class="language-typescript"><code class="language-typescript">export async function allowDomain(domain: string) { 595 await fetch(`${BASE_URL}/allow`, { 596 method: 'POST', 597 headers: headers(), 598 body: JSON.stringify({ domain }), 599 }); 600}</code></pre> 601 602 <h5 id="example-nextjs-report" class="mt-3">Report</h5> 603<pre class="language-typescript"><code class="language-typescript">export async function reportDomain(domain: string, comment?: string) { 604 await fetch(`${BASE_URL}/report`, { 605 method: 'POST', 606 headers: headers(), 607 body: JSON.stringify({ domain, comment }), 608 }); 609}</code></pre> 610 611 <h3 id="example-python" class="mt-5">Python</h3> 612 <p class="text-muted small">Uses the <code>requests</code> library. The shape is identical with <code>httpx</code> or stdlib <code>urllib.request</code>.</p> 613 614 <h5 id="example-python-setup" class="mt-3">Setup</h5> 615<pre class="language-python"><code class="language-python">import os 616import requests 617 618BASE_URL = 'https://www.istempmail.com/api' 619HEADERS = {'Authorization': f'Bearer {os.environ["ITM_TOKEN"]}'}</code></pre> 620 621 <h5 id="example-python-check" class="mt-3">Check</h5> 622<pre class="language-python"><code class="language-python">email = '[email protected]' 623r = requests.get(f'{BASE_URL}/check/{email}', headers=HEADERS, timeout=5) 624r.raise_for_status() 625if r.json().get('blocked'): 626 raise ValueError('Disposable email')</code></pre> 627 628 <h5 id="example-python-block" class="mt-3">Block</h5> 629<pre class="language-python"><code class="language-python">requests.post(f'{BASE_URL}/block', headers=HEADERS, 630 json={'domain': 'spam-domain.example', 'comment': 'Repeated abuse'})</code></pre> 631 632 <h5 id="example-python-allow" class="mt-3">Allow</h5> 633<pre class="language-python"><code class="language-python">requests.post(f'{BASE_URL}/allow', headers=HEADERS, 634 json={'domain': 'partner.example'})</code></pre> 635 636 <h5 id="example-python-report" class="mt-3">Report</h5> 637<pre class="language-python"><code class="language-python">requests.post(f'{BASE_URL}/report', headers=HEADERS, 638 json={'domain': 'new-temp-mail.example'})</code></pre> 639 640 <h3 id="example-ruby" class="mt-5">Ruby</h3> 641 <p class="text-muted small">Standard library only (<code>net/http</code>) — no gem dependency. A small <code>istempmail_verify</code> helper covers all four endpoints.</p> 642 643 <h5 id="example-ruby-setup" class="mt-3">Setup</h5> 644<pre class="language-ruby"><code class="language-ruby">
644require 'net/http' 645require 'json' 646require 'uri' 647 648BASE_URL = 'https://www.istempmail.com/api' 649TOKEN = ENV.fetch('ITM_TOKEN') 650 651def istempmail_verify(method:, path:, body: nil) 652 uri = URI("#{BASE_URL}#{path}") 653 req = (method == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri) 654 req['Authorization'] = "Bearer #{TOKEN}" 655 if body 656 req['Content-Type'] = 'application/json' 657 req.body = JSON.generate(body) 658 end 659 res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) } 660 JSON.parse(res.body) 661end</code></pre> 662 663 <h5 id="example-ruby-check" class="mt-3">Check</h5> 664<pre class="language-ruby"><code class="language-ruby">email = '[email protected]' 665data = istempmail_verify(method: :get, path: "/check/#{URI.encode_www_form_component(email)}") 666raise 'Disposable email' if data['blocked']</code></pre> 667 668 <h5 id="example-ruby-block" class="mt-3">Block</h5> 669<pre class="language-ruby"><code class="language-ruby">istempmail_verify(method: :post, path: '/block', 670 body: { domain: 'spam-domain.example', comment: 'Repeated abuse' })</code></pre> 671 672 <h5 id="example-ruby-allow" class="mt-3">Allow</h5> 673<pre class="language-ruby"><code class="language-ruby">istempmail_verify(method: :post, path: '/allow', body: { domain: 'partner.example' })</code></pre> 674 675 <h5 id="example-ruby-report" class="mt-3">Report</h5> 676<pre class="language-ruby"><code class="language-ruby">istempmail_verify(method: :post, path: '/report', body: { domain: 'new-temp-mail.example' })</code></pre> 677 678 <h3 id="example-go" class="mt-5">Go</h3> 679 <p class="text-muted small">Idiomatic <code>net/http</code> — drop into a Go module to wrap the API. No third-party dependencies.</p> 680 681 <h5 id="example-go-setup" class="mt-3">Setup</h5> 682<pre class="language-go"><code class="language-go">package itm 683 684import ( 685 "bytes" 686 "encoding/json" 687 "fmt" 688 "net/http" 689 "net/url" 690 "os" 691) 692 693const BaseURL = "https://www.istempmail.com/api" 694 695func istempmailVerify(method, path string, body any) (*http.Response, error) { 696 var buf *bytes.Buffer 697 if body != nil { 698 b, _ := json.Marshal(body) 699 buf = bytes.NewBuffer(b) 700 } else { 701 buf = bytes.NewBuffer(nil) 702 } 703 req, err := http.NewRequest(method, BaseURL+path, buf) 704 if err != nil { 705 return nil, err 706 } 707 req.Header.Set("Authorization", "Bearer "+os.Getenv("ITM_TOKEN")) 708 if body != nil { 709 req.Header.Set("Content-Type", "application/json") 710 } 711 return http.DefaultClient.Do(req) 712}</code></pre> 713 714 <h5 id="example-go-check" class="mt-3">Check</h5> 715<pre class="language-go"><code class="language-go">type CheckResult struct { 716 Name string `json:"name"` 717 Blocked bool `json:"blocked"` 718 Unresolvable bool `json:"unresolvable,omitempty"` 719} 720 721func CheckEmail(email string) (*CheckResult, error) { 722 resp, err := istempmailVerify(http.MethodGet, fmt.Sprintf("/check/%s", url.PathEscape(email)), nil) 723 if err != nil { 724 return nil, err 725 } 726 defer resp.Body.Close() 727 var r CheckResult 728 return &r, json.NewDecoder(resp.Body).Decode(&r) 729}</code></pre> 730 731 <h5 id="example-go-block" class="mt-3">Block</h5> 732<pre class="language-go"><code class="language-go">func Block(domain, comment string) error { 733 resp, err := istempmailVerify(http.MethodPost, "/block", map[string]string{ 734 "domain": domain, "comment": comment, 735 }) 736 if err == nil { 737 resp.Body.Close() 738 } 739 return err 740}</code></pre> 741 742 <h5 id="example-go-allow" class="mt-3">Allow</h5> 743<pre class="language-go"><code class="language-go">func Allow(domain string) error { 744 resp, err := istempmailVerify(http.MethodPost, "/allow", map[string]string{"domain": domain}) 745 if err == nil { 746 resp.Body.Close() 747 } 748 return err 749}</code></pre> 750 751 <h5 id="example-go-report" class="mt-3">Report</h5> 752<pre class="language-go"><code class="language-go">func Report(domain, comment string) error { 753 resp, err := istempmailVerify(http.MethodPost, "/report", map[string]string{ 754 "domain": domain, "comment": comment, 755 }) 756 if err == nil { 757 resp.Body.Close() 758 } 759 return err 760}</code></pre> 761 762 <h3 id="example-php" class="mt-5">PHP</h3> 763 <p class="text-muted small">No-dependency setup using <code>file_get_contents</code> with a stream context. Swap in Guzzle or Symfony HttpClient if you prefer.</p> 764 765 <h5 id="example-php-setup" class="mt-3">Setup</h5> 766<pre class="language-php"><code class="language-php">$baseUrl = 'https://www.istempmail.com/api'; 767$token = getenv('ITM_TOKEN'); 768 769function istempmail_verify(string $method, string $path, ?array $body = null): array { 770 global $baseUrl, $token; 771 $opts = [ 772 'method' => $method, 773 'header' => 'Authorization: Bearer ' . $token, 774 ]; 775 if ($body !== null) { 776 $opts['header'] .= "\r\nContent-Type: application/json"; 777 $opts['content'] = json_encode($body); 778 } 779 $response = file_get_contents($baseUrl . $path, false, stream_context_create(['http' => $opts])); 780 if ($response === false) { 781 throw new RuntimeException('IsTempMail request failed'); 782 } 783 return json_decode($response, true); 784}</code></pre> 785 786 <h5 id="example-php-check" class="mt-3">Check</h5> 787<pre class="language-php"><code class="language-php">$email = '[email protected]'; 788$data = istempmail_verify('GET', '/check/' . rawurlencode($email)); 789if ($data['blocked'] ?? false) { 790 throw new RuntimeException('Disposable email'); 791}</code></pre> 792 793 <h5 id="example-php-block" class="mt-3">Block</h5> 794<pre class="language-php"><code class="language-php">istempmail_verify('POST', '/block', ['domain' => 'spam-domain.example', 'comment' => 'Repeated abuse']);</code></pre> 795 796 <h5 id="example-php-allow" class="mt-3">Allow</h5> 797<pre class="language-php"><code class="language-php">istempmail_verify('POST', '/allow', ['domain' => 'partner.example']);</code></pre> 798 799 <h5 id="example-php-report" class="mt-3">Report</h5> 800<pre class="language-php"><code class="language-php">istempmail_verify('POST', '/report', ['domain' => 'new-temp-mail.example']);</code></pre> 801 802 <h3 id="example-java" class="mt-5">Java</h3> 803 <p class="text-muted small">Java 11+ standard library only (<code>java.net.http.HttpClient</code>) — no external dependency. Pair with Jackson or your JSON library of choice for response parsing.</p> 804 805 <h5 id="example-java-setup" class="mt-3">Setup</h5> 806<pre class="language-java"><code class="language-java">import java.net.URI; 807import java.net.http.HttpClient; 808import java.net.http.HttpRequest; 809import java.net.http.HttpRequest.BodyPublishers;
810import java.net.http.HttpResponse.BodyHandlers; 811 812static final String BASE_URL = "https://www.istempmail.com/api"; 813static final HttpClient HTTP = HttpClient.newHttpClient(); 814 815static HttpRequest.Builder istempmailVerify(String path) { 816 return HttpRequest.newBuilder() 817 .uri(URI.create(BASE_URL + path)) 818 .header("Authorization", "Bearer " + System.getenv("ITM_TOKEN")) 819 .header("Content-Type", "application/json"); 820}</code></pre> 821 822 <h5 id="example-java-check" class="mt-3">Check</h5> 823<pre class="language-java"><code class="language-java">String email = URLEncoder.encode("[email protected]", StandardCharsets.UTF_8); 824HttpRequest req = istempmailVerify("/check/" + email).GET().build(); 825HttpResponse<String> res = HTTP.send(req, BodyHandlers.ofString()); 826// parse res.body() with Jackson/Gson; check for "blocked": true</code></pre> 827 828 <h5 id="example-java-block" class="mt-3">Block</h5> 829<pre class="language-java"><code class="language-java">String body = "{\"domain\":\"spam-domain.example\",\"comment\":\"Repeated abuse\"}"; 830HTTP.send(istempmailVerify("/block").POST(BodyPublishers.ofString(body)).build(), 831 BodyHandlers.ofString());</code></pre> 832 833 <h5 id="example-java-allow" class="mt-3">Allow</h5> 834<pre class="language-java"><code class="language-java">HTTP.send(istempmailVerify("/allow") 835 .POST(BodyPublishers.ofString("{\"domain\":\"partner.example\"}")).build(), 836 BodyHandlers.ofString());</code></pre> 837 838 <h5 id="example-java-report" class="mt-3">Report</h5> 839<pre class="language-java"><code class="language-java">HTTP.send(istempmailVerify("/report") 840 .POST(BodyPublishers.ofString("{\"domain\":\"new-temp-mail.example\"}")).build(), 841 BodyHandlers.ofString());</code></pre> 842 843 <h3 id="example-csharp" class="mt-5">C# / .NET</h3> 844 <p class="text-muted small">.NET 6+ — <code>HttpClient</code> from the BCL plus <code>System.Text.Json</code>. No NuGet packages required.</p> 845 846 <h5 id="example-csharp-setup" class="mt-3">Setup</h5> 847<pre class="language-csharp"><code class="language-csharp">using System.Net.Http; 848using System.Net.Http.Json; 849using System.Net.Http.Headers; 850 851const string BaseUrl = "https://www.istempmail.com/api"; 852 853var http = new HttpClient { BaseAddress = new Uri(BaseUrl + "/") }; 854http.DefaultRequestHeaders.Authorization = 855 new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ITM_TOKEN"));</code></pre> 856 857 <h5 id="example-csharp-check" class="mt-3">Check</h5> 858<pre class="language-csharp"><code class="language-csharp">var email = Uri.EscapeDataString("[email protected]"); 859var data = await http.GetFromJsonAsync<Dictionary<string, object>>($"check/{email}"); 860if ((bool)data!["blocked"]) throw new Exception("Disposable email");</code></pre> 861 862 <h5 id="example-csharp-block" class="mt-3">Block</h5> 863<pre class="language-csharp"><code class="language-csharp">await http.PostAsJsonAsync("block", 864 new { domain = "spam-domain.example", comment = "Repeated abuse" });</code></pre> 865 866 <h5 id="example-csharp-allow" class="mt-3">Allow</h5> 867<pre class="language-csharp"><code class="language-csharp">await http.PostAsJsonAsync("allow", new { domain = "partner.example" });</code></pre> 868 869 <h5 id="example-csharp-report" class="mt-3">Report</h5> 870<pre class="language-csharp"><code class="language-csharp">await http.PostAsJsonAsync("report", new { domain = "new-temp-mail.example" });</code></pre> 871 872 <h3 id="example-rust" class="mt-5">Rust</h3> 873 <p class="text-muted small">Using <code>reqwest</code> (blocking or async) and <code>serde_json</code>. The async variant is shown below; swap <code>.await</code> for blocking sync calls if you prefer.</p> 874 875 <h5 id="example-rust-setup" class="mt-3">Setup</h5> 876<pre class="language-rust"><code class="language-rust">use reqwest::Client; 877use serde_json::{json, Value}; 878use std::env; 879 880const BASE_URL: &str = "https://www.istempmail.com/api"; 881 882fn istempmail_verify(client: &Client, method: reqwest::Method, path: &str) -> reqwest::RequestBuilder { 883 client.request(method, format!("{BASE_URL}{path}")) 884 .bearer_auth(env::var("ITM_TOKEN").expect("ITM_TOKEN not set")) 885}</code></pre> 886 887 <h5 id="example-rust-check" class="mt-3">Check</h5> 888<pre class="language-rust"><code class="language-rust">let client = Client::new(); 889let email = urlencoding::encode("[email protected]"); 890let data: Value = istempmail_verify(&client, reqwest::Method::GET, &format!("/check/{email}")) 891 .send().await? 892 .json().await?; 893if data["blocked"].as_bool().unwrap_or(false) { 894 return Err("Disposable email".into()); 895}</code></pre> 896 897 <h5 id="example-rust-block" class="mt-3">Block</h5> 898<pre class="language-rust"><code class="language-rust">istempmail_verify(&client, reqwest::Method::POST, "/block") 899 .json(&json!({"domain": "spam-domain.example", "comment": "Repeated abuse"})) 900 .send().await?;</code></pre> 901 902 <h5 id="example-rust-allow" class="mt-3">Allow</h5> 903<pre class="language-rust"><code class="language-rust">istempmail_verify(&client, reqwest::Method::POST, "/allow") 904 .json(&json!({"domain": "partner.example"})) 905 .send().await?;</code></pre> 906 907 <h5 id="example-rust-report" class="mt-3">Report</h5> 908<pre class="language-rust"><code class="language-rust">istempmail_verify(&client, reqwest::Method::POST, "/report") 909 .json(&json!({"domain": "new-temp-mail.example"})) 910 .send().await?;</code></pre> 911 912 <h3 id="example-cloudflare" class="mt-5">Cloudflare Worker</h3> 913 <p class="text-muted small">Edge-validate signups before they reach your origin. Store the API token as a Worker secret with Wrangler.</p> 914 915 <h5 id="example-cloudflare-setup" class="mt-3">Setup</h5> 916<pre class="language-bash"><code class="language-bash">wrangler secret put ITM_TOKEN 917# paste your 32-character API token when prompted</code></pre> 918<pre class="language-javascript"><code class="language-javascript">const BASE_URL = 'https://www.istempmail.com/api'; 919 920const istempmailVerify = (env, path, init = {}) => fetch(`${BASE_URL}${path}`, { 921 ...init, 922 headers: { 923 Authorization: `Bearer ${env.ITM_TOKEN}`, 924 'Content-Type': 'application/json', 925 ...init.headers, 926 }, 927});</code></pre> 928 929 <h5 id="example-cloudflare-check" class="mt-3">Check</h5> 930<pre class="language-javascript"><code class="language-javascript">export default { 931 async fetch(request, env) { 932 const { email } = await request.json(); 933 const res = await istempmailVerify(env, `/check/${encodeURIComponent(email)}`, 934 { cf: { cacheTtl: 60, cacheEverything: true } }); 935 const data = await res.json(); 936 if (data.blocked) { 937 return Response.json({ error: 'Disposable email' }, { status: 400 }); 938 } 939 return fetch('https://your-origin.example/signup', request); 940 }, 941};</code></pre> 942 943 <h5 id="example-cloudflare-block" class="mt-3">Block</h5> 944<pre class="language-javascript"><code class="language-javascript">await istempmailVerify(env, '/block', { 945 method: 'POST', 946 body: JSON.stringify({ domain: 'spam-domain.example', comment: 'Repeated abuse' }), 947});</code></pre> 948 949 <h5 id="example-cloudflare-allow" class="mt-3">Allow</h5> 950<pre class="language-javascript"><code class="language-javascript">await istempmailVerify(env, '/allow', { 951 method: 'POST', 952 body: JSON.stringify({ domain: 'partner.example' }), 953});</code></pre> 954 955 <h5 id="example-cloudflare-report" class="mt-3">Report</h5> 956<pre class="language-javascript"><code class="language-javascript">await istempmailVerify(env, '/report', { 957 method: 'POST', 958 body: JSON.stringify({ domain: 'new-temp-mail.example' }), 959});</code></pre> 960 961 <h3 id="example-express" class="mt-5">Express</h3> 962 <p class="text-muted small">Signup-form guard plus admin routes for managing your custom lists.</p> 963 964 <h5 id="example-express-setup" class="mt-3">Setup</h5> 965<pre class="language-javascript"><code class="language-javascript">const BASE_URL = 'https://www.istempmail.com/api'; 966 967const istempmailVerify = (path, init = {}) => fetch(`${BASE_URL}${path}`, { 968 ...init, 969 headers: { 970 Authorization: `Bearer ${process.env.ITM_TOKEN}`, 971 'Content-Type': 'application/json', 972 ...init.headers, 973 }, 974});</code></pre> 975 976 <h5 id="example-express-check" class="mt-3">Check (signup-form guard)</h5> 977<pre class="language-javascript"><code class="language-javascript">app.post('/signup', async (req, res) => { 978 const { email } = req.body; 979 try { 980 const result = await (await istempmailVerify(`/check/${encodeURIComponent(email)}`)).json(); 981 if (result.blocked) return res.status(400).json({ error: 'Please use a permanent email address.' }); 982 if (result.unresolvable) return res.status(400).json({ error: "That domain doesn't look right â typo?" }); 983 } catch (err) { 984 console.error('IsTempMail check failed', err); // fail-open 985 } 986 // ...continue signup 987});</code></pre> 988 989 <h5 id="example-express-block" class="mt-3">Block</h5> 990<pre class="language-javascript"><code class="language-javascript">app.post('/admin/block-domain', adminOnly, async (req, res) => { 991 await istempmailVerify('/block', { 992 method: 'POST', 993 body: JSON.stringify({ domain: req.body.domain, comment: req.body.comment }), 994 }); 995 res.sendStatus(204); 996});</code></pre> 997 998 <h5 id="example-express-allow" class="mt-3">Allow</h5> 999<pre class="language-javascript"><code class="language-javascript">app.post('/admin/allow-domain', adminOnly, async (req, res) => { 1000 await istempmailVerify('/allow', { method: 'POST', body: JSON.stringify({ domain: req.body.domain }) }); 1001 res.sendStatus(204); 1002});</code></pre> 1003 1004 <h5 id="example-express-report" class="mt-3">Report</h5> 1005<pre class="language-javascript"><code class="language-javascript">app.post('/admin/report-domain', adminOnly, async (req, res) => { 1006 await istempmailVerify('/report', { method: 'POST', body: JSON.stringify({ domain: req.body.domain }) }); 1007 res.sendStatus(204); 1008});</code></pre> 1009 1010 <h3 id="example-wordpress" class="mt-5">WordPress</h3> 1011 <p>Install the free <a href="https://wordpress.org/plugins/block-temporary-email/" rel="noopener" target="_blank">Block Temporary Email plugin</a>. Drop in your API token, pick the forms you want to protect (registration, comments, WooCommerce checkout, Gravity Forms, etc.) and you’re done — no code required.</p> 1012 </section> 1013 1014 <section id="faq" class="mb-5"> 1015 <h2>FAQ</h2> 1016 1017 <h5>How fresh is the block list?</h5> 1018 <p>Updated multiple times per day. We see 20 to 50 new disposable providers and domains each day.</p> 1019 1020 <h5>Can I check an email locally without hitting the API?</h5> 1021 <p>Not available with the regular paid plans. Local enterprise deployments are available on request.</p> 1022 1023 <h5>What happens if your API is down?</h5> 1024 <p>Decide your fail policy in your integration: fail-open (let the signup through) or fail-closed (block until the API responds). Most customers fail-open and rely on downstream checks.</p> 1025 1026 <h5>Will you tell me <em>why</em> a domain is blocked?</h5> 1027 <p>Not currently. Domains are flagged based on an aggregate of signals and manual review. The check endpoint returns a yes/no answer only.</p> 1028 1029 <h5>Does <code>
1029blocked: false</code> guarantee the address exists?</h5> 1030 <p>No. It guarantees the domain isn’t a known disposable provider. Use <code>unresolvable: true</code> to spot dead domains, but a positive <code>blocked: false</code> doesn’t promise the inbox accepts mail.</p> 1031 1032 <h5>Can I check multiple domains in one request?</h5> 1033 <p>You can use the Bulk check in feature through the Dashboard. Just copy and paste your domains, and click once to get all verified. For now, send one request per domain — the API is fast enough that this is rarely a bottleneck.</p> 1034 1035 <h5>Do you log the emails I check?</h5> 1036 <p>We never log email addresses. We discard the local part before the actual verification step and do not store it. We do keep logs of the <strong>domain</strong> for the rolling 30-day quota window. See our <a href="/legal/privacy-policy">privacy policy</a> for details.</p> 1037 1038 <h5>How do I rotate my token?</h5> 1039 <p>From your dashboard. The old token stops working immediately, so update your integrations first. Multiple tokens per account are available in enterprise plans – <a href="mailto:[email protected]">talk to sales</a> if interested.</p> 1040 1041 <h5>What happens if my subscription lapses or my card fails?</h5> 1042 <p>Paddle subscribers get a <strong>7-day grace period</strong> after the expiry date — the API keeps working while the retry happens. After that, requests return <code>403 "Your account has expired."</code> until you renew. Manual (non-subscription) accounts have no grace period; the API stops at the expiry date.</p> 1043 <p>For credit card failures, we will retry to charge. If the payment keeps failing, your subscription will be disabled.</p> 1044 1045 <h5>Do you have an SLA?</h5> 1046 <p>We offer SLAs for entrprise customers. Please <a href="mailto:[email protected]">talk to sales</a> for more information.</p> 1047 1048 <h5>Is there a Zapier / Make integration?</h5> 1049 <p>Our API is easy to use on both platforms via the generic HTTP step. Just provide your token and you are good to go.</p> 1050 </section> 1051 1052 <div class="text-center my-5"> 1053 <a href="/sign-up" class="btn btn-lg btn-primary" style="font-size:1.25rem;padding:.75rem 2rem;"> 1054 Get started for free 1055 </a> 1056 <p class="mt-2 text-muted small"> 1057 Sign up and get your API token in seconds — no credit card required. 1058 </p> 1059 </div> 1060 1061 1062 <p class="text-center mt-5"> 1063 <a href="#overview" class="text-decoration-none">↑ Back to top</a> 1064 </p> 1065 </main> 1066 </div> 1067</div> 1068
1069<script> 1070(function () { 1071 function attach() { 1072 document.querySelectorAll('.docs-content pre[class*="language-"]').forEach(function (pre) { 1073 if (pre.querySelector('.copy-btn')) return; 1074 var btn = document.createElement('button'); 1075 btn.type = 'button'; 1076 btn.className = 'copy-btn'; 1077 btn.textContent = 'Copy'; 1078 btn.addEventListener('click', function () { 1079 var code = (pre.querySelector('code') || pre).textContent; 1080 navigator.clipboard.writeText(code).then(function () { 1081 btn.textContent = 'Copied!'; 1082 btn.classList.add('copied'); 1083 setTimeout(function () { 1084 btn.textContent = 'Copy'; 1085 btn.classList.remove('copied'); 1086 }, 1400); 1087 }).catch(function () { 1088 btn.textContent = 'Failed'; 1089 setTimeout(function () { btn.textContent = 'Copy'; }, 1400); 1090 }); 1091 }); 1092 pre.appendChild(btn); 1093 }); 1094 } 1095 if (document.readyState === 'loading') { 1096 document.addEventListener('DOMContentLoaded', attach); 1097 } else { 1098 attach(); 1099 } 1100})(); 1101</script>
1101 1102
1102<script defer data-domain="istempmail.com" src="https://blip.istempmail.com/blip.js"></script>
1102 1103</body> 1104</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.