Getting Started with Mailoo

This guide walks through the pieces Mailoo actually ships today: projects, FORM / CONTACT_FORM / JSBOX / BLOG integrations, webhook + API key access, and the dashboard surfaces that show messages and subscribers.

Prerequisites

Before you begin, make sure you have:

A Mailoo account (through your configured identity provider)
A project in the dashboard where integrations and API keys live
Somewhere safe to store API keys (server, BFF, or automation runner—not the browser bundle)

Tip

Create separate API keys per environment (staging vs production) and prefer RESTRICTED scopes until you know exactly which webhook each integration needs.

Creating your account

Start from the sign-in page and follow these steps:

Open the Mailoo homepage and choose Get started free or Sign in.
Complete authentication with your identity provider (Keycloak, etc.).
When you land in the dashboard, create or select a project.
Note the project UID—you will reference it in webhooks and public blog URLs.

You can return to the dashboard anytime; session handling follows your deployment's Auth.js and IdP settings.

Setting up your first integration

Mailoo does not connect third-party mailboxes. Instead you add an integration that matches how visitors interact with your site:

Step 1: Open the integrations workspace

Inside your project, open Integrations (or choose Add integration from the project overview).
Review the integration types that are available for your plan.
Pick FORM, CONTACT_FORM, JSBOX, or BLOG depending on the experience you are building.

Step 2: Configure integration-specific settings

Provide a clear name so teammates know which site or form it represents.
Set allowed origins, webhook URLs, or widget options required for that type.
Generate an API key with the scopes that match your webhook (for example form submissions vs chat).
Store the key in your server environment—never embed FULL keys in client-side JavaScript.
Save the integration and confirm it shows as Active in the dashboard.

Step 3: Connect your application code

Point your backend or BFF at the documented webhook path using HTTPS.
Forward subscriber or contact payloads using the shapes described in the integration guide.
For JSBOX, add the loader snippet and pass the integration identifiers Mailoo provides.
Optional: configure outbound SMTP on the integration before sending subscriber mail from Mailoo.

Testing your integration

Validate the path end-to-end before you go live:

Trigger a test submission from a staging environment (form post, chat session, or blog publish).
Wait for the webhook response or dashboard refresh—most paths complete within seconds.
Open Messages in the dashboard and confirm metadata, status, and integration linkage.
For FORM integrations, verify Subscribers reflects the test email you used.

Troubleshooting

If nothing appears after a few minutes:

• Confirm the API key scope matches the webhook you called.
• Double-check the project UID and integration ID in the URL or payload.
• Look for 4xx responses in your server logs (signature, CORS, or validation errors).
• Contact support with the integration ID and approximate timestamp so we can trace the request.

Next steps

Once the first integration is healthy, extend your setup:

Add another integration type (for example JSBOX next to an existing FORM).
Configure templates and campaigns for subscriber messaging.
Read the website forms guide for BFF patterns in Next.js.
Open the hosted OpenAPI document at /docs/v1 on your API deployment for exhaustive schemas.