Provides iframe to connect mailboxes such as Microsoft, Google, Custom SMTP, etc.
(Embed form is required in order to connect Microsoft mailboxes into Mailivery)
This endpoint lets your application obtain a temporary, signed link to Mailivery’s hosted mailbox‑connect form. You embed or redirect users to the link so they can authorize their Microsoft 365, Gmail, or other inbox without you handling OAuth credentials yourself. Once the user completes the form, Mailivery automatically creates or updates the warm‑up campaign and sends a webhook to your server.
Request summary
- Method: GET
- Authentication: Bearer API key in the
Authorizationheader - Base path:
/api/v1/embed/form/secure
Optional query parameters
| Name | Type | Purpose |
|---|---|---|
tags | String (comma‑separated) | Labels you want Mailivery to attach to the campaign that will be created after the user connects. Example value agency123,trial. |
Rate‑limit: Maximum 10 requests per second per API key.
Response summary (HTTP 200)
The endpoint returns a JSON object with two fields:
| Field | Type | Description |
|---|---|---|
url | String | A one‑time link to the Mailivery connect form. |
expiresIn | Number | Time‑to‑live in seconds (normally 900 seconds, i.e., 15 minutes). |
After expiresIn seconds the link is invalid; request a new one if the user has not clicked it in time.
Typical usage flow
- User action – In your product, the user chooses “Connect inbox.”
- Backend call – Your server calls this endpoint and receives the signed link.
- Frontend hand‑off – Pass the link to the browser; either redirect the user or open it in an iframe or modal.
- User completes Mailivery form – They grant mailbox permissions or supply SMTP details. The window then closes or redirects as you specify.
- Webhook notification – Mailivery notifies your webhook endpoint of either success or failure (see the next section).
- Store campaign ID – On success, read the
campaignIdfrom the webhook payload and keep it for subsequent warm‑up operations.
Webhook events you will receive
| Event | When it fires | Key payload fields |
|---|---|---|
inbox.connected | Mailbox connection succeeded and a campaign was created or updated. | campaignId, email, tags |
inbox.connection_error | The user abandoned the flow or OAuth / SMTP verification failed. | error, email (if available) |
Configure your webhook URL in the Mailivery dashboard under Settings → Webhooks.
Common error responses
| HTTP Status | Error code | Meaning & action |
|---|---|---|
| 401 | INVALID_API_KEY | The token is missing or malformed. Supply a valid Bearer token. |
| 429 | RATE_LIMIT_EXCEEDED | You exceeded 10 requests per second. Retry later with exponential back‑off. |
| 500 | EMBED_LINK_GENERATION_FAILED | Internal error while generating the link. Retry; contact support if it persists. |
When not to use this endpoint
- If you already collect SMTP/IMAP credentials yourself – skip the embed flow and create the campaign directly via
POST /campaigns/smtp,.../gmail, or.../sendgrid. - If you only need to re‑connect a Microsoft mailbox – call
PATCH /campaigns/{id}with an empty body; Mailivery returns a dedicated reconnect link for that mailbox.
Key takeaway
Use GET /embed/form/secure whenever you want Mailivery to handle the entire OAuth and credential capture process for your users, while you focus on the surrounding UX and receive a clean webhook when everything is set up.