Get started with the Developers page
The Developers page in your mailfloss dashboard brings together API keys, webhooks and the apps you build. Use an API key to call mailfloss from your own tools. Use Your apps when you want other mailfloss users to connect to an app you build.
You can try the API from the mailfloss Postman collection or Apidog docs site before writing an integration.
Before you start
Sign in to your mailfloss account as an owner or admin to create API keys or apps. If an API-key action returns Access denied, ask your account owner or admin for help.
Keep API keys and app secrets private. Never put them in a public collection, screenshot, support message or source repository. The examples below describe requests; they do not promise a particular verification result.
Choose the right tab
Tab | Use it to |
|---|---|
API keys | View your keys. Owners and admins can create and manage keys for calls to the mailfloss API. |
Webhooks | Choose events mailfloss sends to a URL on your server. |
Your apps | Owners and admins can create an app that other mailfloss users authorize to access their account. |
The API docs link opens the developer reference.
Create an API key
- Open Developers → API keys and choose Create API key.
- Give the key a name that describes its use, such as “Postman test,” and choose an expiry or Never.
- Choose Restricted and select the permissions needed for your request. A single-email verification request needs Verify emails (verify).
- Create the key and save it securely when it appears. The full key is shown only once.
Use the key as a Bearer token. Keep it server-side in your integration. If you lose it, create a replacement and update the tools that use it. Revoking a key immediately stops anything using that key.
Try a request in Postman or Apidog
- Open the Postman collection or Apidog docs site.
- Set up your request in a private working copy or private local session. Supply your mailfloss API key as the Bearer token; do not save it into shared or published examples.
- Choose GET /v1/verify at https://api.mailfloss.com, and set the email query parameter to an address you are authorized to check.
- Send the request. On success, inspect the JSON fields status, reason and passed. The verdict depends on the address; a successful HTTP request does not itself mean the address passed verification.
Each successful verification consumes one account credit. Start with one address. The Quick Start explains the response and links to the full API reference for further requests.
Receive events with Webhooks
Open Developers → Webhooks. Webhooks are available on the Business plan or as an add-on. If the tab shows an availability message, check your account's access before trying to add one.
Choose Add webhook to configure the receiving URL, source and events. mailfloss sends a JSON POST to the URL when a selected event occurs. Open an existing webhook to manage it. Refer to the developer documentation for event payloads and delivery details before connecting your server.
Test a webhook and check its deliveries
Open Developers → Webhooks, then open a webhook to see its own page.
- Send test event posts a sample payload to your endpoint, so you can check your setup without waiting for real activity. It makes one attempt.
- Recent deliveries shows the latest attempts for that webhook and how your server answered.
For real events, any 2xx response counts as delivered. If your server doesn't answer with a 2xx, mailfloss tries again up to 5 times over about 20 minutes, then turns Sending off for that webhook.
Build an app for other mailfloss users
Owners and admins can open Developers → Your apps → Create app. An app uses an authorization flow so users can approve its requested permissions, rather than handing you their API key.
Follow Build an app on mailfloss for the app name, redirect URIs, permissions and server-side setup. Save the client secret securely when it is shown. New, unverified apps have a warning on the consent page and a limit of 100 connections. Use the app's Get verified tab when you are ready to submit it for review.
An app you have connected to your account is managed separately under Account Settings → Connected apps, where you can disconnect it.
Troubleshooting
- The key is no longer visible: the full key appears only at creation. Use your saved copy or create a replacement.
- A restricted key gets a 403: check that it includes the permission required by that request. Do not broaden access beyond what your integration needs.
- The request fails: read the API error's code and consult the developer reference. Keep the key out of any error report you share.
- The Postman profile cannot be found: use the collection link in this article, not postman.com/mailfloss.
- You want to manage an app you connected: go to Account Settings → Connected apps. Your apps is for apps you create.