# Agent setup
Source: https://docs.minimo.it/agent-setup

Point your AI agent at this page and it will connect itself to Minimo.

<Info>
  This page doubles as an **executable prompt**. Copy the block below into your AI coding agent (Claude Code, Cursor,
  Codex, Copilot, …) and it will connect itself to the Minimo MCP server. The raw instructions are also available at
  [`https://docs.minimo.it/agent-setup.md`](https://docs.minimo.it/agent-setup.md).
</Info>

## Copy this into your agent

```text theme={null}
Fetch and execute the instructions at https://docs.minimo.it/agent-setup.md to connect me to Minimo.
```

That's it. Your agent reads the steps below, adds the Minimo MCP server with the right command for
your tool, and confirms when it's done.

***

## Instructions for the agent

These are official instructions from Minimo to connect an AI agent to a Minimo workspace via the
**Model Context Protocol (MCP)**. Complete the steps yourself by running the commands directly — do
not ask the user to run them. The Minimo MCP endpoint is `https://api.minimo.it/mcp` (Streamable
HTTP). Authentication is OAuth ("Sign in with Minimo"): on first tool use a browser window opens and
the user clicks **Authorize** — there is no key to copy. For headless or CI environments, use an
`mn-…` API key with the `mcp:invoke` permission as a Bearer header instead.

### Claude Code

```bash theme={null}
claude mcp add --transport http minimo https://api.minimo.it/mcp
```

### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)

Add under `"mcpServers"`:

```json theme={null}
"minimo": { "url": "https://api.minimo.it/mcp" }
```

### Codex

```bash theme={null}
codex mcp add minimo --url https://api.minimo.it/mcp
```

### GitHub Copilot (VS Code) — `.vscode/mcp.json`, Windsurf, and other agents

Add under `"mcpServers"` (Windsurf uses `serverUrl` instead of `url`):

```json theme={null}
"minimo": { "url": "https://api.minimo.it/mcp" }
```

### Headless / CI (no browser to sign in)

Pass an API key as a Bearer header. Get one from **Settings → Mo & MCP** (the "Use Mo everywhere"
card) or **Developer → API keys** with the **MCP (AI agent)** permission.

```bash theme={null}
claude mcp add --transport http minimo https://api.minimo.it/mcp \
  --header "Authorization: Bearer mn-YOUR-API-KEY"
```

### Verify

After connecting, confirm it works by asking the agent a read-only question:

```text theme={null}
Using Minimo: which workspace am I connected to, and how many contacts do I have?
```

If the agent returns a workspace name and a contact count, the connection is live. Then tell the user:

```
✓ Minimo connected. Your agent can now read and act on your workspace — contacts, segments,
  email & WhatsApp templates, campaigns and automations — through Mo's tools.
```

<Note>
  These instructions are published at `https://docs.minimo.it/agent-setup.md` so you can re-verify their authenticity at
  any time. For the human-readable walkthrough per client, see [Connect your agent (MCP)](/guides/connect-your-agent).
</Note>


# Delete Contact
Source: https://docs.minimo.it/api-reference/core-data/contacts/delete

delete /public/v1/contacts/{id}
Soft-delete a contact by ID

<Note>
  This performs a **soft delete** — the contact is marked as deleted but not permanently removed from the database.
  Soft-deleted contacts can be restored by calling the [upsert](/api-reference/core-data/contacts/upsert) or [update by
  ID](/api-reference/core-data/contacts/update-by-id) endpoint.
</Note>

## Common Errors

| Error          | Cause                   | Solution                               |
| -------------- | ----------------------- | -------------------------------------- |
| `not_found`    | No contact with this ID | Verify the contact ID                  |
| `unauthorized` | Invalid API key         | Verify API key in Authorization header |

## Related Endpoints

* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Create a new contact or restore a deleted one
* **[Get Contact by Email](/api-reference/core-data/contacts/get-by-email)**: Look up a contact by email
* **[Update Contact by ID](/api-reference/core-data/contacts/update-by-id)**: Update a specific contact


# Get Contact by Email
Source: https://docs.minimo.it/api-reference/core-data/contacts/get-by-email

get /public/v1/contacts/by-email/{email}
Retrieve a contact and all its data by email address

<Tip>
  Use this endpoint to look up a contact's ID, then use **[Update by
  ID](/api-reference/core-data/contacts/update-by-id)** to modify it — for example, to change the contact's email
  address.
</Tip>

## Use Cases

* **Look up contact ID**: Find a contact's internal ID to use with other endpoints
* **Check if contact exists**: Verify whether an email is already in your contact list
* **Read contact data**: Retrieve full contact details including custom fields

## Response

Returns the full contact object:

```json theme={null}
{
  "data": {
    "id": 42,
    "email": "customer@example.com",
    "phone": "+393391234567",
    "status": "active",
    "source": "API",
    "custom_fields": {
      "company": "Acme Corp",
      "plan": "enterprise"
    },
    "company": 1,
    "deleted": false,
    "external_id": null,
    "external_connection_id": null
  }
}
```

<Note>Soft-deleted contacts are not returned — a `404` is returned instead.</Note>

## Common Errors

| Error          | Cause                      | Solution                               |
| -------------- | -------------------------- | -------------------------------------- |
| `bad_request`  | Invalid email format       | Ensure the email address is valid      |
| `not_found`    | No contact with this email | Check the email address                |
| `unauthorized` | Invalid API key            | Verify API key in Authorization header |

## Example: Look Up and Update a Contact

```javascript theme={null}
const API_URL = 'https://api.minimo.it/public/v1/contacts';
const headers = {
  Authorization: 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
  'Content-Type': 'application/json',
};

// Step 1: Get the contact by email
const email = 'customer@example.com';
const contact = await fetch(`${API_URL}/by-email/${encodeURIComponent(email)}`, { headers }).then((res) => res.json());

// Step 2: Update the contact by ID (e.g., change email)
await fetch(`${API_URL}/${contact.data.id}`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({ email: 'new-email@example.com' }),
});
```

## Related Endpoints

* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Upsert a contact by email or phone
* **[Update Contact by ID](/api-reference/core-data/contacts/update-by-id)**: Update a specific contact
* **[Delete Contact](/api-reference/core-data/contacts/delete)**: Soft-delete a contact


# Update Contact by ID
Source: https://docs.minimo.it/api-reference/core-data/contacts/update-by-id

put /public/v1/contacts/{id}
Update an existing contact using their ID

<Tip>
  Unlike the [upsert endpoint](/api-reference/core-data/contacts/upsert) which matches by email or phone, this endpoint
  updates a specific contact by their ID. Use this when you need a deterministic update by ID — especially when changing
  a contact's email address.
</Tip>

## When to Use This

| Scenario                     | Use this endpoint | Use upsert instead                                                          |
| ---------------------------- | ----------------- | --------------------------------------------------------------------------- |
| Change a contact's email     | Yes               | Only if phone number is also provided (upsert falls back to phone matching) |
| Update a known contact by ID | Yes               | Either works                                                                |
| Create a new contact         | No (returns 404)  | Yes                                                                         |
| Update by email/phone match  | No                | Yes                                                                         |

## How It Works

* **Only provided fields are updated** — omitted fields are preserved
* **Custom fields are deep merged** — existing custom fields not included in the request are kept
* **Automations are triggered** — field change detection and automation triggers work the same as upsert
* **Soft-deleted contacts are restored** — if the contact was deleted, it will be restored with the provided data

## Marketing Consent

Update channel-specific marketing consent for a contact:

```json theme={null}
{
  "marketingConsent": {
    "email": true,
    "whatsapp": false
  }
}
```

| Field      | Type    | Description                                             |
| ---------- | ------- | ------------------------------------------------------- |
| `email`    | boolean | Email marketing opt-in (`true`) or opt-out (`false`)    |
| `whatsapp` | boolean | WhatsApp marketing opt-in (`true`) or opt-out (`false`) |

<Info>
  Both fields are optional. Omitting a channel leaves its current consent status unchanged. Setting `true` opts the
  contact in, `false` opts them out.
</Info>

<Warning>
  This endpoint does **not** create new contacts. If no contact exists with the given ID, a `404` error is returned.
</Warning>

## Example: Change a Contact's Email

<Steps>
  <Step title="Look up the contact by email">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.minimo.it/public/v1/contacts/by-email/old@example.com' \
      --header 'Authorization: Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY'
    ```

    Response: `{ "data": { "id": 42, "email": "old@example.com", ... } }`
  </Step>

  <Step title="Update using the contact ID">
    ```bash theme={null}
    curl --request PUT \
      --url 'https://api.minimo.it/public/v1/contacts/42' \
      --header 'Authorization: Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{ "email": "new@example.com" }'
    ```
  </Step>
</Steps>

## Common Errors

| Error          | Cause                   | Solution                               |
| -------------- | ----------------------- | -------------------------------------- |
| `not_found`    | No contact with this ID | Verify the contact ID                  |
| `unauthorized` | Invalid API key         | Verify API key in Authorization header |

## Related Endpoints

* **[Get Contact by Email](/api-reference/core-data/contacts/get-by-email)**: Look up a contact's ID by email
* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Upsert by email or phone
* **[Delete Contact](/api-reference/core-data/contacts/delete)**: Soft-delete a contact


# Create or Update Contact
Source: https://docs.minimo.it/api-reference/core-data/contacts/upsert

post /public/v1/contacts
Insert a new contact or update an existing one based on email or phone

<Tip>
  This endpoint performs an **upsert**: it first tries to match by email, then falls back to phone if no email match is
  found. If no match is found, a new contact is created.
</Tip>

## How Matching Works

The endpoint matches contacts in this order:

<Steps>
  <Step title="Match by email">
    If `email` is provided, searches for an existing contact with the same email in your company.
  </Step>

  <Step title="Match by phone">If no email match is found and `phone` is provided, searches by phone number.</Step>
  <Step title="Create new">If no match is found, creates a new contact.</Step>
</Steps>

<Info>
  Need to update a contact's email? Prefer **[Update by ID](/api-reference/core-data/contacts/update-by-id)** for a
  deterministic update. Upsert only avoids creating a new record if a phone number is also provided and matches an
  existing contact.
</Info>

## Custom Fields

Store additional data using the `customFields` object. Fields are flexible key-value pairs:

```json theme={null}
{
  "email": "customer@example.com",
  "customFields": {
    "company": "Acme Corp",
    "plan": "enterprise",
    "signup_date": "2025-11-13"
  }
}
```

When updating an existing contact, custom fields are **deep merged** — only the fields you include are changed, existing fields are preserved.

## Marketing Consent

Control channel-specific marketing consent when creating or updating a contact:

```json theme={null}
{
  "email": "customer@example.com",
  "marketingConsent": {
    "email": true,
    "whatsapp": false
  }
}
```

| Field      | Type    | Description                                             |
| ---------- | ------- | ------------------------------------------------------- |
| `email`    | boolean | Email marketing opt-in (`true`) or opt-out (`false`)    |
| `whatsapp` | boolean | WhatsApp marketing opt-in (`true`) or opt-out (`false`) |

<Info>
  Both fields are optional. Omitting a channel leaves its current consent status unchanged. Setting `true` opts the
  contact in, `false` opts them out.
</Info>

## Phone Numbers

For WhatsApp messaging, include a phone number in **E.164 format**:

```json theme={null}
{
  "email": "customer@example.com",
  "phone": "+393391234567"
}
```

**Format requirements**:

* Include country code (e.g., `+39` for Italy, `+1` for US)
* No spaces, dashes, or parentheses
* Example: `+12025551234` (US), `+393391234567` (Italy)

<Warning>Invalid phone numbers will cause WhatsApp message sending to fail.</Warning>

## Common Errors

| Error                  | Cause                     | Solution                               |
| ---------------------- | ------------------------- | -------------------------------------- |
| `validation_error`     | Invalid email format      | Check email address format             |
| `invalid_phone_number` | Phone not in E.164 format | Add country code, remove spaces        |
| `rate_limit_exceeded`  | Too many requests         | Implement rate limiting, use batching  |
| `unauthorized`         | Invalid API key           | Verify API key in Authorization header |

## Related Endpoints

* **[Get Contact by Email](/api-reference/core-data/contacts/get-by-email)**: Look up a contact by email
* **[Update Contact by ID](/api-reference/core-data/contacts/update-by-id)**: Update a specific contact by ID
* **[Delete Contact](/api-reference/core-data/contacts/delete)**: Soft-delete a contact
* **[Custom Fields](/api-reference/core-data/custom-fields/list)**: Manage custom field definitions


# Create Custom Field
Source: https://docs.minimo.it/api-reference/core-data/custom-fields/create

post /public/v1/custom-fields
Create a new custom field to store additional contact data

<Tip>
  Custom fields allow you to define and organize additional attributes for your contacts beyond the standard fields
  (email, phone, name).
</Tip>

## Use Cases

* **Lead qualification**: Store lead score, source, or stage
* **Segmentation**: Categorize contacts by industry, plan, or region
* **Personalization**: Store preferences for personalized messaging
* **Integration sync**: Map external CRM fields to Minimo

## Field Types

| Type       | Description                   |
| ---------- | ----------------------------- |
| `text`     | Free text input               |
| `number`   | Numeric value                 |
| `boolean`  | True/false                    |
| `date`     | Date value                    |
| `datetime` | Date and time                 |
| `select`   | Single selection from options |
| `json`     | JSON object                   |

## Best Practices

<AccordionGroup>
  <Accordion title="Use Consistent Naming">
    Use `SNAKE_CASE` for keys (e.g., `COMPANY_SIZE`, `LEAD_SOURCE`). Keys are automatically uppercased.
  </Accordion>

  <Accordion title="Organize with Categories">
    Group related fields using categories like "Company Info", "Lead Data", "Preferences" for better organization.
  </Accordion>

  <Accordion title="Plan Field Types">
    Choose the right type for your data. Use `number` for numeric values, `date` for dates, and `select` for predefined options.
  </Accordion>
</AccordionGroup>

## Common Errors

| Error                | Cause                    | Solution                           |
| -------------------- | ------------------------ | ---------------------------------- |
| `key already exists` | Duplicate key in account | Use a different key name           |
| `validation_error`   | Missing required fields  | Include key, displayName, and type |
| `unauthorized`       | Invalid API key          | Check Authorization header         |

## Code Examples

<AccordionGroup>
  <Accordion title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.minimo.it/public/v1/custom-fields', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        key: 'LEAD_SOURCE',
        displayName: 'Lead Source',
        type: 'select',
        category: 'Lead Data'
      })
    });
    const { data } = await response.json();
    console.log(data);
    ```
  </Accordion>

  <Accordion title="Python">
    ```python theme={null}
    import requests

    headers = {
        'Authorization': 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.minimo.it/public/v1/custom-fields',
        headers=headers,
        json={
            'key': 'LEAD_SOURCE',
            'displayName': 'Lead Source',
            'type': 'select',
            'category': 'Lead Data'
        }
    )
    print(response.json())
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

* **[List Custom Fields](/api-reference/core-data/custom-fields/list)**: Retrieve all custom fields
* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Create and update contacts with custom field values


# List Custom Fields
Source: https://docs.minimo.it/api-reference/core-data/custom-fields/list

get /public/v1/custom-fields
Retrieve all custom fields defined for your account

<Tip>Use the `groupBy=category` query parameter to get custom fields organized by category for easier management.</Tip>

## Use Cases

* **Display field options**: Show available custom fields in your application UI
* **Integration mapping**: Map external CRM fields to Minimo custom fields
* **Data validation**: Check which fields exist before creating contacts

## Group by Category

Get custom fields organized by category by adding the `groupBy=category` query parameter:

```bash theme={null}
curl --request GET \
  --url 'https://api.minimo.it/public/v1/custom-fields?groupBy=category' \
  --header 'Authorization: Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY'
```

**Grouped Response:**

```json theme={null}
{
  "data": {
    "groups": [
      {
        "category": "Company Info",
        "fields": [
          { "id": 1, "key": "COMPANY_SIZE", "displayName": "Company Size", "type": "text" },
          { "id": 2, "key": "INDUSTRY", "displayName": "Industry", "type": "select" }
        ]
      },
      {
        "category": "uncategorized",
        "fields": [{ "id": 3, "key": "NOTES", "displayName": "Notes", "type": "text" }]
      }
    ],
    "total": 3
  }
}
```

<Note>Fields without a category are automatically grouped under `uncategorized`.</Note>

## Field Types

| Type       | Description                   |
| ---------- | ----------------------------- |
| `text`     | Free text input               |
| `number`   | Numeric value                 |
| `boolean`  | True/false                    |
| `date`     | Date value                    |
| `datetime` | Date and time                 |
| `select`   | Single selection from options |
| `json`     | JSON object                   |

## Common Errors

| Error              | Cause                 | Solution                             |
| ------------------ | --------------------- | ------------------------------------ |
| `unauthorized`     | Invalid API key       | Check Authorization header format    |
| `invalid_group_by` | Invalid groupBy value | Use `category` or omit the parameter |

## Related Endpoints

* **[Create Custom Field](/api-reference/core-data/custom-fields/create)**: Create a new custom field
* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Create and update contacts with custom field values


# Legacy API (Deprecated)
Source: https://docs.minimo.it/api-reference/legacy/introduction

Deprecated endpoints maintained for backward compatibility

<Warning>
  **This section contains deprecated endpoints that will be removed on June 1, 2026.** Please migrate to the new
  endpoints in the [Messaging Channels](/api-reference/messaging-channels/email/send-template) section.
</Warning>

## Why These Endpoints Are Deprecated

The original "Transactionals" API had several limitations:

* ❌ Inconsistent naming and structure
* ❌ Limited template management capabilities
* ❌ No support for WhatsApp and other channels
* ❌ Unclear separation between channels
* ❌ Missing analytics and tracking features

The new **Messaging Channels** API addresses all these issues with:

* ✅ Consistent structure across all channels
* ✅ Better template management
* ✅ Multi-channel support (Email, WhatsApp, SMS coming soon)
* ✅ Enhanced analytics and stats
* ✅ Improved error handling and validation

## Migration Guide

### Email Transactionals → Email Templates

**Old endpoint** (deprecated):

```bash theme={null}
POST /api/transactionals
```

**New endpoint**:

```bash theme={null}
POST /public/v1/templates/email/send
```

### Request Structure Comparison

<CodeGroup>
  ```json Old (Deprecated) theme={null}
  {
    "uid": "unique_template_id",
    "recipient": "customer@example.com",
    "customFields": {
      "name": "John Doe",
      "orderNumber": "12345"
    }
  }
  ```

  ```json New (Recommended) theme={null}
  {
    "uid": "tmpl_abc123",
    "recipient": "customer@example.com",
    "customFields": {
      "name": "John Doe",
      "orderNumber": "12345"
    }
  }
  ```
</CodeGroup>

**Key changes**:

* Template IDs now use `tmpl_` prefix for clarity
* Response includes more metadata

### WhatsApp Migration

**Old endpoint** (deprecated):

```bash theme={null}
POST /api/transactionals/whatsapp/send
GET /api/transactionals/whatsapp/templates
```

**New endpoints** (on `api.minimo.it`):

```bash theme={null}
POST https://api.minimo.it/public/v1/templates/whatsapp/send
GET  https://api.minimo.it/public/v1/templates/whatsapp
```

The structure is largely the same, but with improved error messages and validation. Note the new endpoints are served from the `api.minimo.it` domain.

## Migration Timeline

| Date              | Milestone                                           |
| ----------------- | --------------------------------------------------- |
| **November 2025** | New API released, legacy API deprecated             |
| **December 2025** | Migration guide published                           |
| **March 2026**    | Legacy API enters maintenance mode (bug fixes only) |
| **May 2026**      | Final migration warnings sent to all users          |
| **June 1, 2026**  | **Legacy API removed**                              |

<Info>
  You have until **June 1, 2026** to migrate. After this date, the legacy endpoints will return `410 Gone` errors.
</Info>

## How to Migrate

<Steps>
  <Step title="Audit Your Integration">
    Identify where you're using the old endpoints:

    ```bash theme={null}
    # Search your codebase
    grep -r "/api/transactionals" .
    ```
  </Step>

  <Step title="Update API Calls">
    Replace old endpoints with new ones:

    * `/api/transactionals` → `/public/v1/templates/email/send`
    * `/api/transactionals/whatsapp/send` → `/public/v1/templates/whatsapp/send`
    * `/api/transactionals/whatsapp/templates` → `/public/v1/templates/whatsapp`
  </Step>

  <Step title="Update Request Payloads">
    Verify template IDs in your request payloads:

    ```javascript theme={null}
    // Before
    { uid: "abc123", recipient: "user@example.com" }

    // After (templated ID prefixed with tmpl_)
    { uid: "tmpl_abc123", recipient: "user@example.com" }
    ```
  </Step>

  <Step title="Test in Staging">
    Verify the new endpoints work as expected in your staging environment before deploying to production.
  </Step>

  <Step title="Deploy to Production">
    Once tested, deploy your changes to production.
  </Step>

  <Step title="Monitor & Verify">
    Check logs to ensure no errors and that messages are being delivered successfully.
  </Step>
</Steps>

## Get Migration Help

Need assistance migrating?

* **Email support**: [info@minimo.it](mailto:info@minimo.it)
* **Documentation**: [New Messaging Channels API](/api-reference/messaging-channels/email/send-template)
* **Dashboard**: Check your API usage at [app.minimo.it/account](https://app.minimo.it/account)

<Tip>We're here to help! If you encounter any issues during migration, reach out to our support team.</Tip>

## Still Using Legacy Endpoints?

If you're still using the deprecated endpoints below, you'll see deprecation warnings in API responses:

```json theme={null}
{
  "data": {
    /* your response */
  },
  "warning": {
    "message": "This endpoint is deprecated and will be removed on June 1, 2026",
    "deprecationDate": "2026-06-01",
    "migrateTo": "/public/v1/templates/email/send",
    "docsUrl": "https://docs.minimo.it/api-reference/messaging-channels/email/send-template"
  }
}
```

Use these warnings to track which integrations need updating.


# List Email Transactionals (Deprecated)
Source: https://docs.minimo.it/api-reference/legacy/list-email-transactionals-deprecated

Retrieve list of email transactionals - deprecated endpoint

<Warning>
  **This endpoint is deprecated and will be removed on June 1, 2026.** Please migrate to the new [List Email
  Templates](/api-reference/messaging-channels/email/list-templates) endpoint.
</Warning>

## Why This Is Deprecated

This endpoint has been replaced with a clearer, more consistent API structure.

### Use the New Endpoint Instead

**New endpoint**: `GET /public/v1/templates/email`

[View new endpoint documentation →](/api-reference/messaging-channels/email/list-templates)

## Migration

The new endpoint provides more information and better filtering:

### Old Response (This Endpoint)

```json theme={null}
{
  "templates": [
    {
      "uid": "abc123",
      "name": "Order Confirmation"
    }
  ]
}
```

### New Response (Recommended)

```json theme={null}
{
  "data": [
    {
      "id": "tmpl_abc123",
      "name": "Order Confirmation",
      "subject": "Your order is confirmed",
      "status": "active",
      "category": "transactional",
      "createdAt": "2025-10-01T10:00:00Z",
      "variables": ["orderNumber", "customerName"]
    }
  ]
}
```

**Benefits of new endpoint**:

* ✅ More template metadata
* ✅ Status and category information
* ✅ List of template variables
* ✅ Timestamps for auditing
* ✅ Consistent naming (`id` instead of `uid`)

## Migration Deadline

This endpoint will be removed on **June 1, 2026**.

[Read the full migration guide →](/api-reference/legacy/introduction)

## Need Help?

* [Migration Guide](/api-reference/legacy/introduction)
* [New Email Templates API](/api-reference/messaging-channels/email/list-templates)
* [Contact Support](mailto:info@minimo.it)


# Send Email (Deprecated)
Source: https://docs.minimo.it/api-reference/legacy/send-email-deprecated

post /api/transactionals

<Warning>
  **This endpoint is deprecated and will be removed on June 1, 2026.** Please migrate to the new [Send Email
  Template](/api-reference/messaging-channels/email/send-template) endpoint.
</Warning>

## Why This Is Deprecated

This endpoint has been replaced with a more flexible and consistent API under **Messaging Channels**.

### What's Wrong With This Endpoint?

* Inconsistent with other channel APIs
* Limited error handling
* No support for advanced template features

### Use the New Endpoint Instead

**New endpoint**: `POST /public/v1/templates/email/send`

[View new endpoint documentation →](/api-reference/messaging-channels/email/send-template)

## Migration

### Old Request (This Endpoint)

```json theme={null}
{
  "uid": "unique_template_id",
  "recipient": "customer@example.com",
  "customFields": {
    "name": "John Doe",
    "orderNumber": "12345"
  }
}
```

### New Request (Recommended)

```json theme={null}
{
  "uid": "tmpl_abc123",
  "recipient": "customer@example.com",
  "customFields": {
    "name": "John Doe",
    "orderNumber": "12345"
  }
}
```

**Changes needed**:

1. Update endpoint URL: `/api/transactionals` → `/public/v1/templates/email/send`
2. Update template IDs in your code (now prefixed with `tmpl_`)

## Migration Deadline

| Date          | Status                             |
| ------------- | ---------------------------------- |
| November 2025 | Deprecated (still works)           |
| June 1, 2026  | **Removed** (will return 410 Gone) |

<Info>You have until **June 1, 2026** to migrate. Plan your migration now to avoid service disruption.</Info>

## Need Help?

* [Migration Guide](/api-reference/legacy/introduction)
* [New Email API Docs](/api-reference/messaging-channels/email/send-template)
* [Contact Support](mailto:info@minimo.it)


# Get One-Shot Email Statistics
Source: https://docs.minimo.it/api-reference/messaging-channels/email/html-stats

get /public/v1/emails/{id}/stats
Poll delivery, open, and click metrics for a single HTML email sent via the one-shot endpoint

## Overview

After dispatching an email through [`POST /public/v1/emails`](/api-reference/messaging-channels/email/send-html), use the returned `id` (or the full `statsUrl`) to read back delivery and engagement metrics for that **single** delivery.

Unlike the template-stats endpoint, these numbers refer to **one recipient and one HTML payload** — not aggregated counters across a campaign.

<Tip>
  The endpoint is scoped to your company. IDs that belong to a different company return `404`, never another tenant's
  data.
</Tip>

## Request

```bash theme={null}
curl --request GET \
  --url https://api.minimo.it/public/v1/emails/DMPNEF8/stats \
  --header 'Authorization: Bearer mn-{apiClientId}-{secret}'
```

## Response Example

```json theme={null}
{
  "data": {
    "id": "DMPNEF8",
    "status": "sent",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "sentAt": "2026-05-19T10:30:00Z",
    "opened": true,
    "firstOpenAt": "2026-05-19T10:32:14Z",
    "clickCount": 2,
    "firstClickAt": "2026-05-19T10:33:05Z",
    "failureReason": null
  }
}
```

## Field Reference

| Field           | Type                              | Description                                                                 |
| --------------- | --------------------------------- | --------------------------------------------------------------------------- |
| `id`            | `string`                          | Echo of the opaque sqid id returned by the POST endpoint.                   |
| `status`        | `"pending" \| "sent" \| "failed"` | Lifecycle state of the delivery.                                            |
| `to`            | `string`                          | Recipient address as it was sent.                                           |
| `subject`       | `string`                          | Subject line as it was sent.                                                |
| `sentAt`        | `date-time`                       | When the delivery row was created (queue-in time, not provider acceptance). |
| `opened`        | `boolean`                         | `true` once the tracking pixel has been fetched at least once.              |
| `firstOpenAt`   | `date-time \| null`               | Timestamp of the first open; `null` until the pixel is fetched.             |
| `clickCount`    | `integer`                         | Total number of clicks across all tracked links in the email.               |
| `firstClickAt`  | `date-time \| null`               | Timestamp of the earliest tracked click; `null` until the first click.      |
| `failureReason` | `string \| null`                  | Populated when `status = "failed"` — the provider's rejection reason.       |

## How the Counters Are Updated

* **Open**: triggered the first time the recipient's email client fetches the embedded `<img>` open-pixel. Image proxies (Gmail, Apple Mail Privacy Protection) trigger this immediately on arrival, which inflates open rates compared to pre-2021 baselines.
* **Click**: every fetch of a rewritten `/api/click/...` URL appends a row to the click ledger. `clickCount` is the cardinality of that ledger; `firstClickAt` is its minimum timestamp.

Both signals are **per delivery**: opens and clicks tied to a different `id` do not affect this row.

## Use Cases

<AccordionGroup>
  <Accordion title="Confirm a magic link landed">
    After sending a sign-in email, poll the stats endpoint to surface "Email opened by recipient" in your internal dashboard.

    ```javascript theme={null}
    const { data: stats } = await fetch(`https://api.minimo.it/public/v1/emails/${id}/stats`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    }).then((r) => r.json());

    if (stats.opened) {
      console.log(`Magic link opened at ${stats.firstOpenAt}`);
    }
    ```
  </Accordion>

  <Accordion title="Detect failed deliveries in a queue worker">
    When `status === "failed"`, persist `failureReason` against the originating business object so support can react.

    ```javascript theme={null}
    const { data: stats } = await getEmailStats(id);
    if (stats.status === 'failed') {
      await logDeliveryFailure({ id, reason: stats.failureReason });
    }
    ```
  </Accordion>

  <Accordion title="Attribute a CTA click back to the trigger">
    The first click timestamp lets you measure end-to-end latency from "we sent it" to "user acted."

    ```javascript theme={null}
    const { data: stats } = await getEmailStats(id);
    if (stats.firstClickAt) {
      const sentAt = new Date(stats.sentAt);
      const clickedAt = new Date(stats.firstClickAt);
      const minutesToFirstClick = (clickedAt - sentAt) / 60000;
      track('email_click_latency_minutes', minutesToFirstClick);
    }
    ```
  </Accordion>
</AccordionGroup>

## Common Errors

| Status | Cause                                                                                              |
| ------ | -------------------------------------------------------------------------------------------------- |
| `401`  | API key missing or malformed.                                                                      |
| `403`  | API key lacks the `TRANSACTIONAL` permission.                                                      |
| `404`  | The `id` doesn't exist, or it belongs to a different company than the one this API key authorizes. |

## Polling Guidance

* **Open events**: usually surface within seconds for image-proxied clients (Gmail, Apple Mail Privacy Protection). For other clients, wait until the recipient actually opens the message.
* **Click events**: stored synchronously the moment the rewritten URL is fetched — they appear in the next stats response.
* **Rate**: a steady cadence of one poll every 30–60 seconds for the first \~10 minutes is plenty. Aggressive polling won't surface data faster.

## Related Endpoints

* [Send One-Shot HTML Email](/api-reference/messaging-channels/email/send-html) — the producer side of these statistics
* [Get Email Template Stats](/api-reference/messaging-channels/email/stats) — aggregated stats for template-backed sends


# List Email Templates
Source: https://docs.minimo.it/api-reference/messaging-channels/email/list-templates

get /public/v1/templates/email
Retrieve all email templates available in your Minimo account

## Overview

Get a list of all email templates you've created in the Minimo dashboard. Use this endpoint to:

* Display available templates in your application
* Verify template IDs before sending emails
* Build template selection interfaces
* Audit your template library

## Response Structure

The response includes template metadata:

```json theme={null}
{
  "data": [
    {
      "id": "tmpl_abc123",
      "name": "Order Confirmation",
      "subject": "Your order {{orderNumber}} is confirmed",
      "status": "active",
      "category": "transactional",
      "createdAt": "2025-10-01T10:00:00Z",
      "updatedAt": "2025-11-01T15:30:00Z",
      "variables": ["orderNumber", "customerName", "total"]
    },
    {
      "id": "tmpl_xyz789",
      "name": "Welcome Email",
      "subject": "Welcome to {{companyName}}!",
      "status": "active",
      "category": "marketing",
      "createdAt": "2025-09-15T09:00:00Z",
      "updatedAt": "2025-09-15T09:00:00Z",
      "variables": ["companyName", "firstName"]
    }
  ]
}
```

## Template Categories

Templates can belong to different categories:

| Category        | Description                          | Examples                           |
| --------------- | ------------------------------------ | ---------------------------------- |
| `transactional` | Order-related, account notifications | Order confirmation, password reset |
| `marketing`     | Promotional campaigns                | Product launch, newsletter         |
| `automated`     | Triggered by user behavior           | Welcome series, abandoned cart     |

## Template Status

| Status     | Description                  |
| ---------- | ---------------------------- |
| `active`   | Template is ready to use     |
| `draft`    | Template is being edited     |
| `archived` | Template is no longer in use |

<Info>Only `active` templates can be used with the Send Email Template endpoint.</Info>

## Use Cases

### Template Selector UI

Build a dropdown to let users choose templates:

```javascript theme={null}
async function loadTemplates() {
  const response = await fetch('https://api.minimo.it/public/v1/templates/email', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const { data: templates } = await response.json();

  // Filter only active templates
  const activeTemplates = templates.filter((t) => t.status === 'active');

  // Populate dropdown
  const select = document.getElementById('template-select');
  activeTemplates.forEach((template) => {
    const option = document.createElement('option');
    option.value = template.id;
    option.textContent = template.name;
    select.appendChild(option);
  });
}
```

### Validate Template ID

Before sending an email, verify the template exists:

```javascript theme={null}
async function isValidTemplate(templateId) {
  const response = await fetch('https://api.minimo.it/public/v1/templates/email', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const { data: templates } = await response.json();

  return templates.some((t) => t.id === templateId && t.status === 'active');
}
```

## Filtering (Coming Soon)

Future versions will support filtering:

```bash theme={null}
GET /public/v1/templates/email?category=transactional&status=active
```

## Related Endpoints

* [Send Email Template](/api-reference/messaging-channels/email/send-template) - Send emails using templates
* [Get Email Template Stats](/api-reference/messaging-channels/email/stats) - View template performance


# Send One-Shot HTML Email
Source: https://docs.minimo.it/api-reference/messaging-channels/email/send-html

post /public/v1/emails
Dispatch a single transactional email by sending a pre-rendered HTML payload — no template required

## Overview

Use this endpoint when you want to send a transactional email **without
creating a template** in the dashboard. You provide the rendered HTML
yourself and Minimo handles dispatch, delivery, and tracking.

Typical use cases:

* **Server-side rendered receipts**: invoices, order confirmations, shipping notifications
* **Authentication flows**: magic links, OTP delivery, email verification
* **Internal notifications**: alerts produced by your own background jobs
* **Anything dynamic enough to not fit a pre-defined template**

<Tip>
  Tracking (open pixel + click rewriting) is injected **server-side**. Send your raw HTML as-is — don't pre-rewrite
  links or append a pixel yourself.
</Tip>

## Before You Start

1. Generate an API key with the **`TRANSACTIONAL`** permission from the Minimo dashboard.
2. Make sure your company's email provider is configured (SMTP or SES).
3. Have your HTML body ready — Minimo doesn't render templates for this endpoint.

## What the Server Does to Your HTML

When you send `html`, the backend:

1. **Resolves placeholders**: `{{UNSUBSCRIBE_URL}}`, `{{PREFERENCES_URL}}`, and `{{FAKE_IMAGE_URL}}` are replaced with the per-recipient tracked URLs.
2. **Strips any pre-existing tracking pixel**: an `<img>` whose `src` matches the Minimo open-pixel pattern is removed so it can't double-fire.
3. **Rewrites tracked anchors**: every `<a href>` pointing to `http(s)` or a relative URL is replaced with a click-tracking URL. `mailto:`, fragment-only (`#…`), and pre-existing `/api/click/*` links are left alone.
4. **Appends the open-tracking pixel** at the end of `<body>` (or at the document root if no `<body>` exists).

The recipient receives the final HTML; analytics flow into `GET /public/v1/emails/{id}/stats`.

## Example Request

```bash theme={null}
curl --request POST \
  --url https://api.minimo.it/public/v1/emails \
  --header 'Authorization: Bearer mn-{apiClientId}-{secret}' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "customer@example.com",
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase. <a href=\"https://example.com/receipt/12345\">View receipt</a></p>"
  }'
```

## Response Shape

The endpoint **always returns HTTP 200** when authentication succeeds — inspect `status` to know whether the provider accepted the message.

```json theme={null}
{
  "data": {
    "id": "DMPNEF8",
    "status": "sent",
    "messageId": "0100019c8b3d4a4f-...",
    "statsUrl": "/public/v1/emails/DMPNEF8/stats"
  }
}
```

When the provider rejects the message you still get back the same `id`, so the delivery row remains queryable:

```json theme={null}
{
  "data": {
    "id": "DMPNEF8",
    "status": "failed",
    "failureReason": "Email address is not verified.",
    "statsUrl": "/public/v1/emails/DMPNEF8/stats"
  }
}
```

## Use Cases

<AccordionGroup>
  <Accordion title="Order receipt with embedded link">
    Render the receipt server-side and post it raw — Minimo rewrites the `View receipt` anchor into a tracked link.

    ```json theme={null}
    {
      "to": "customer@example.com",
      "subject": "Receipt for ORD-12345",
      "html": "<h1>Thanks, Jane!</h1><p>Your order <strong>ORD-12345</strong> is on the way.</p><p><a href=\"https://shop.example.com/orders/ORD-12345\">Track your order</a></p>"
    }
    ```
  </Accordion>

  <Accordion title="Magic-link sign-in">
    Override the sender per request to brand the email for a specific product surface.

    ```json theme={null}
    {
      "to": "newuser@example.com",
      "subject": "Sign in to Acme",
      "html": "<p>Hi! Click <a href=\"https://app.example.com/auth?token=eyJ...\">here</a> to sign in. Link expires in 15 minutes.</p>",
      "fromAddress": "no-reply@acme.com",
      "fromName": "Acme Sign-In"
    }
    ```
  </Accordion>

  <Accordion title="Internal alert from a background job">
    Plain HTML with a single CTA is enough — the open and click events surface in the stats endpoint.

    ```json theme={null}
    {
      "to": "ops@example.com",
      "subject": "[ALERT] Queue depth above threshold",
      "html": "<p>Worker queue at 12,400 jobs.</p><p><a href=\"https://admin.example.com/jobs\">Open dashboard</a></p>",
      "text": "Worker queue at 12,400 jobs. Open dashboard: https://admin.example.com/jobs"
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

### Pair every send with a `statsUrl` lookup

The response includes `statsUrl`. Persist the `id` (or the full `statsUrl`) alongside whatever business object triggered the send (order id, user id, etc.) so you can correlate opens and clicks later.

### Handle the `failed` branch

`status: "failed"` means the provider rejected the message — usually a malformed recipient, an unverified sender, or a hard bounce. Surface `failureReason` to your operators, then either retry with corrected data or log the failure.

### Keep HTML self-contained

Inline your CSS. Many email clients drop `<style>` blocks. Test in major clients (Gmail, Apple Mail, Outlook) before going live.

### Provide a `text` fallback for deliverability

Spam filters reward multipart messages. Adding a plain-text alternative reduces the chance of landing in the junk folder.

### Don't double-track

If your HTML already contains `/api/click/*` URLs or an open pixel from a previous Minimo send, leave them alone — the server detects and skips them. Inserting your own tracking on top is unnecessary.

## Common Errors

| Status | Body                                                  | Cause                                              |
| ------ | ----------------------------------------------------- | -------------------------------------------------- |
| `400`  | `{ "error": "to must be an email" }`                  | Invalid or missing required field                  |
| `401`  | —                                                     | API key missing or wrong format                    |
| `403`  | —                                                     | API key lacks the `TRANSACTIONAL` permission       |
| `200`  | `{ "data": { "status": "failed", "failureReason" } }` | Provider rejected the message (still a `200`)      |
| `500`  | —                                                     | Server misconfiguration (e.g. `WEB_APP_URL` unset) |

## Related Endpoints

* [Get One-Shot Email Statistics](/api-reference/messaging-channels/email/html-stats) — poll opens and clicks for a delivery
* [Send Email Template](/api-reference/messaging-channels/email/send-template) — same idea, but starting from a dashboard template


# Send Email Template
Source: https://docs.minimo.it/api-reference/messaging-channels/email/send-template

post /public/v1/templates/email/send
Send transactional or automated emails using predefined templates

## Overview

Use this endpoint to send emails based on templates you've created in the Minimo dashboard. Perfect for:

* **Transactional emails**: Order confirmations, password resets, receipts
* **Automated messages**: Welcome series, onboarding flows
* **Triggered notifications**: Account alerts, status updates

<Tip>
  This API is intended for **server-side usage only**. Requests from client-side applications will be blocked for
  security reasons.
</Tip>

## Before You Start

1. **Create a template** in the Minimo dashboard under Templates → Email
2. **Get the template ID** from the templates list
3. **Define custom fields** in your template using `{{variableName}}` syntax
4. **Test your template** using the dashboard preview before API integration

## Template Variables

Templates support dynamic content using variables:

**Template Example**:

```html theme={null}
Hello {{firstName}}, Your order {{orderNumber}} has been confirmed! Total: {{orderTotal}} Estimated delivery:
{{deliveryDate}}
```

**API Request**:

```json theme={null}
{
  "uid": "tmpl_abc123",
  "recipient": "customer@example.com",
  "customFields": {
    "firstName": "Jane",
    "orderNumber": "ORD-12345",
    "orderTotal": "$99.99",
    "deliveryDate": "November 20, 2025"
  }
}
```

## Use Cases

<AccordionGroup>
  <Accordion title="Order Confirmation">
    Send instant confirmation when an order is placed:

    ```json theme={null}
    {
      "uid": "tmpl_order_confirm",
      "recipient": "customer@example.com",
      "customFields": {
        "orderNumber": "ORD-12345",
        "items": "3 items",
        "total": "$149.99",
        "trackingUrl": "https://track.example.com/12345"
      }
    }
    ```
  </Accordion>

  <Accordion title="Password Reset">
    Send password reset links securely:

    ```json theme={null}
    {
      "uid": "tmpl_password_reset",
      "recipient": "user@example.com",
      "customFields": {
        "resetLink": "https://app.example.com/reset?token=abc123",
        "expiresIn": "24 hours"
      }
    }
    ```
  </Accordion>

  <Accordion title="Welcome Email">
    Onboard new users with a welcome message:

    ```json theme={null}
    {
      "uid": "tmpl_welcome",
      "recipient": "newuser@example.com",
      "customFields": {
        "firstName": "John",
        "loginUrl": "https://app.example.com/login",
        "supportEmail": "support@example.com"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

### Email Deliverability

<Tip>
  To improve deliverability: - Use verified sender domains in Minimo dashboard - Avoid spam trigger words in templates -
  Include unsubscribe links for marketing emails - Test with email testing tools before production
</Tip>

### Template Design

* **Keep it simple**: Plain text or simple HTML works best
* **Test responsiveness**: Templates should work on mobile devices
* **Include branding**: Add your logo and brand colors
* **Clear call-to-action**: Make buttons and links obvious

### Error Handling

Always handle potential errors:

```javascript theme={null}
try {
  const response = await fetch('https://api.minimo.it/public/v1/templates/email/send', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      uid: 'tmpl_abc123',
      recipient: 'customer@example.com',
      customFields: { name: 'Jane' },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('Email send failed:', error);
    // Log error, retry, or notify admin
  }
} catch (error) {
  console.error('Network error:', error);
  // Handle network issues
}
```

## Common Errors

| Error                  | Cause                          | Solution                             |
| ---------------------- | ------------------------------ | ------------------------------------ |
| `template_not_found`   | Invalid template ID            | Verify template ID in dashboard      |
| `invalid_recipient`    | Invalid email address          | Validate email format before sending |
| `missing_custom_field` | Template variable not provided | Include all required custom fields   |
| `rate_limit_exceeded`  | Too many requests              | Implement rate limiting, use queues  |
| `sender_not_verified`  | Email domain not verified      | Verify sender domain in dashboard    |

## Tracking & Analytics

After sending, track email performance:

* **Delivery status**: Check if email was delivered
* **Open rate**: See who opened your emails
* **Click rate**: Track link clicks in your templates
* **Bounce rate**: Monitor bounced emails

Access analytics in the Minimo dashboard or via the [Get Email Template Stats](/api-reference/messaging-channels/email/stats) endpoint.

## Related Endpoints

* [List Email Templates](/api-reference/messaging-channels/email/list-templates) - Get all available templates
* [Get Email Template Stats](/api-reference/messaging-channels/email/stats) - View template analytics


# Get Email Template Stats
Source: https://docs.minimo.it/api-reference/messaging-channels/email/stats

get /public/v1/transactionals/{id}/stats
View delivery, open, and click statistics for email templates

## Overview

Track the performance of your email templates with detailed analytics including:

* **Delivery volume**: Total messages sent
* **Engagement rates**: Open rates and click rates
* **Metadata**: Creation timestamp

## Use Cases

<AccordionGroup>
  <Accordion title="Monitor Template Performance">
    Track which templates have the best engagement:

    ```javascript theme={null}
    const templates = await getTemplateList();

    for (const template of templates) {
      const response = await getTemplateStats(template.id);
      const stats = response.data;
      console.log(`${template.name}: ${stats.openRate} open rate`);
    }
    ```
  </Accordion>

  <Accordion title="A/B Testing">
    Compare performance between template variants:

    ```javascript theme={null}
    const responseA = await getTemplateStats('tmpl_variant_a');
    const responseB = await getTemplateStats('tmpl_variant_b');

    const rateA = parseFloat(responseA.data.clickRate);
    const rateB = parseFloat(responseB.data.clickRate);

    if (rateB > rateA) {
      console.log('Template B performs better');
    }
    ```
  </Accordion>

  <Accordion title="Dashboard Widgets">
    Display real-time stats in your application:

    ```javascript theme={null}
    async function updateDashboard() {
      const response = await getTemplateStats('tmpl_welcome');
      const stats = response.data;
      
      document.getElementById('sent-count').textContent = stats.totalMessagesSent;
      document.getElementById('open-rate').textContent = stats.openRate;
      document.getElementById('click-rate').textContent = stats.clickRate;
    }
    ```
  </Accordion>
</AccordionGroup>

## Response Example

```json theme={null}
{
  "data": {
    "created": "2026-06-11T09:50:39.760Z",
    "openRate": "0%",
    "clickRate": "0%",
    "totalMessagesSent": 1
  }
}
```

## Metrics Explained

| Metric              | Type      | Description                                                              |
| ------------------- | --------- | ------------------------------------------------------------------------ |
| `created`           | `string`  | Timestamp when the template/transactional message was created.           |
| `openRate`          | `string`  | Percentage of recipients who opened the message (e.g. "85%").            |
| `clickRate`         | `string`  | Percentage of recipients who clicked a link in the message (e.g. "50%"). |
| `totalMessagesSent` | `integer` | Total number of messages sent using this template.                       |

## Best Practices

### Monitoring Frequency

* **High-volume templates**: Check daily
* **Moderate-volume**: Check weekly
* **Low-volume**: Check monthly

### Setting Alerts

Monitor for engagement drops:

```javascript theme={null}
async function checkTemplateHealth(templateId) {
  const response = await getTemplateStats(templateId);
  const stats = response.data;

  const openRate = parseFloat(stats.openRate);
  if (openRate < 10) {
    alert('Low open rate detected - review subject line and sender name!');
  }
}
```

### Improving Performance

**Low open rate?**

* Test different subject lines
* Optimize send time
* Segment your audience better

**Low click rate?**

* Make CTAs more prominent
* Reduce content complexity
* Test different button styles

## Related Endpoints

* [Send Email Template](/api-reference/messaging-channels/email/send-template) - Send emails with this template
* [List Email Templates](/api-reference/messaging-channels/email/list-templates) - View all templates


# Inbound & Webhooks
Source: https://docs.minimo.it/api-reference/messaging-channels/whatsapp/inbound-webhooks

How Minimo receives WhatsApp replies, delivery events, and template-status updates

## Overview

WhatsApp is **two-way**. Beyond the outbound send endpoints, Minimo receives events
from Meta (WhatsApp Cloud API / 360dialog) through a single webhook and turns them into
things you can see and act on:

* **Inbound messages** — replies your customers send back — appear in the **Inbox** and
  in the contact's chat history.
* **Template-status updates** — when Meta approves or rejects a template you submitted —
  automatically flip the template's `status` (visible via
  [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates)).

<Info>
  This webhook is **managed by Minimo** and is **Meta-facing**, not part of the API-key surface. You do not call it and
  you do not need to configure it — connecting a number in [Channels](https://app.minimo.it/channels) wires up the Meta
  subscription for you. It is documented here so you understand where inbound data and template-status changes come
  from.
</Info>

## Endpoint

Minimo exposes the webhook at:

```
GET  https://api.minimo.it/public/v1/webhooks/whatsapp
POST https://api.minimo.it/public/v1/webhooks/whatsapp
```

### Verification (`GET`)

Meta verifies the subscription with a challenge handshake. Minimo replies with the
`hub.challenge` value when `hub.mode=subscribe` and `hub.verify_token` matches the
configured verify token.

| Query parameter    | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `hub.mode`         | `subscribe` for the verification handshake.           |
| `hub.verify_token` | Shared token Minimo checks against its configuration. |
| `hub.challenge`    | Echoed back verbatim when the token matches.          |

### Events (`POST`)

Meta delivers events to the `POST` route. Minimo always answers `200` quickly, then
processes the payload:

* The company is identified from the inbound `phone_number_id` (multi-sender safe — the
  event is routed to the number that received it).
* `message_template_status_update` changes (contained in `entry[].changes[]`) update the
  matching template's approval status.
* Other events (inbound customer messages) are recorded against the contact and surfaced
  in the Inbox.

<Note>
  Because processing is asynchronous and authentication is via Meta's verify token (not a Minimo API key), this route is
  not shown in the interactive API playground. Consume the results through the **Inbox** and the template-list endpoint
  instead.
</Note>

## What to poll instead

If you need to react programmatically to template approvals, poll
[List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates) and
watch the `status` field flip to `APPROVED` — the webhook keeps that value up to date for
you.

## Related Endpoints

* [Send WhatsApp Template](/api-reference/messaging-channels/whatsapp/send-template) - Outbound sends
* [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates) - Template approval status
* [List WhatsApp Senders](/api-reference/messaging-channels/whatsapp/list-senders) - Connected numbers


# List WhatsApp Senders
Source: https://docs.minimo.it/api-reference/messaging-channels/whatsapp/list-senders

get /public/v1/templates/whatsapp/senders
Discover the connected WhatsApp numbers you can send from (multi-sender / multi-WABA)

## Overview

A single Minimo company can connect **more than one WhatsApp number** — for example a
support line and a marketing line, possibly under different WhatsApp Business Accounts
(WABAs). This endpoint returns the numbers you are allowed to send from, so you know
which values you can pass as the `sender` field of a [WhatsApp send](/api-reference/messaging-channels/whatsapp/send-template).

<Info>
  **Custom numbers for platforms & agencies.** Minimo is a WhatsApp **Business Solution
  Provider (BSP)** on a 360dialog partner plan with unlimited numbers, so you can provision a
  **dedicated, custom number per customer, brand or location** and resell WhatsApp messaging
  without your own Meta BSP contract. This endpoint lists every number the company can send
  from; target a specific one with the `sender` field. See
  [Custom numbers, multiple numbers & agencies](/product/messaging/whatsapp-numbers).
</Info>

The response is a **redacted** view: it deliberately excludes secrets and internal
fields (API keys, client IDs, webhook URLs). It only exposes what you need to pick a
sender.

<Tip>
  Connect and manage your WhatsApp numbers from the **Channels** section at
  [app.minimo.it/channels](https://app.minimo.it/channels).
</Tip>

## Response Structure

```json theme={null}
{
  "items": [
    {
      "phoneNumber": "+393511234567",
      "phoneName": "Acme Support",
      "phoneNumberId": "123456789012345",
      "isPreferred": true
    },
    {
      "phoneNumber": "+393517654321",
      "phoneName": "Acme Marketing",
      "phoneNumberId": "543210987654321",
      "isPreferred": false
    }
  ],
  "pagination": {
    "totalRecords": 2,
    "currentPage": 1,
    "totalPages": 1,
    "nextPage": null,
    "prevPage": null
  }
}
```

## Fields

| Field           | Type      | Description                                                                                               |
| --------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| `phoneNumber`   | `string`  | The display phone number — the primary value to pass as `sender`.                                         |
| `phoneName`     | `string`  | The WhatsApp Business display name of the number.                                                         |
| `phoneNumberId` | `string`  | The Meta `phone_number_id` — also accepted as `sender`. May differ for 360dialog-connected numbers.       |
| `isPreferred`   | `boolean` | Whether this is the company **default** number, used when a send omits `sender`. Exactly one per company. |

## How the sender is resolved on a send

When you call
[`POST /public/v1/templates/whatsapp/send`](/api-reference/messaging-channels/whatsapp/send-template),
Minimo picks the number to send **from** as follows:

1. If you pass `sender`, that number is used. You may pass either the `phoneNumber`
   (in any formatting — E.164, spaces, etc.) or the `phoneNumberId`.
2. If you omit `sender`, the company **preferred** number (`isPreferred: true`) is used.

<Warning>
  Passing a `sender` that isn't one of the company's connected numbers returns `WHATSAPP_SENDER_NOT_FOUND`. Always
  source the value from this endpoint.
</Warning>

## Example: send from a specific number

```bash theme={null}
# 1. Discover the senders
curl https://api.minimo.it/public/v1/templates/whatsapp/senders \
  -H "Authorization: Bearer mn-abc123-xyz789"

# 2. Send FROM the marketing number
curl https://api.minimo.it/public/v1/templates/whatsapp/send \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "recipient": "393471234567",
    "type": "template",
    "sender": "+393517654321",
    "template": {
      "name": "product_launch",
      "components": [
        { "type": "BODY", "parameters": [ { "type": "text", "text": "Jane" } ] }
      ]
    }
  }'
```

## Related Endpoints

* [Send WhatsApp Template](/api-reference/messaging-channels/whatsapp/send-template) - Send messages, optionally from a chosen `sender`
* [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates) - View all available templates


# List WhatsApp Templates
Source: https://docs.minimo.it/api-reference/messaging-channels/whatsapp/list-templates

get /public/v1/templates/whatsapp
Retrieve all WhatsApp templates and their approval status

## Overview

Get a list of all WhatsApp templates in your Minimo account, including their approval status, category, and available components.

Use this endpoint to:

* Check which templates are approved and ready to send
* Display available templates in your application
* Monitor template approval status
* Verify template structure before sending messages

<Tip>
  Before sending messages, make sure to connect a WhatsApp Business Account by visiting the **Channels** section at
  [app.minimo.it/channels](https://app.minimo.it/channels).
</Tip>

## Response Structure

```json theme={null}
{
  "data": [
    {
      "id": "tmpl_whatsapp_123",
      "name": "order_confirmation",
      "language": "en",
      "status": "APPROVED",
      "category": "UTILITY",
      "namespace": "e33bca12_1234_4567_abcd_abcdef123456",
      "createdAt": "2025-10-01T10:00:00Z",
      "updatedAt": "2025-10-05T14:30:00Z",
      "qualityScore": {
        "score": "GREEN",
        "reasons": null
      },
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Order Confirmation"
        },
        {
          "type": "BODY",
          "text": "Hello {{1}}, your order {{2}} has been confirmed!",
          "example": {
            "bodyText": [["John Doe", "ORD-12345"]]
          }
        },
        {
          "type": "FOOTER",
          "text": "Reply STOP to opt out"
        }
      ]
    }
  ]
}
```

## Template Status

WhatsApp templates can have different statuses:

| Status     | Description                | Can Send? |
| ---------- | -------------------------- | --------- |
| `APPROVED` | Template approved by Meta  | ✅ Yes     |
| `PENDING`  | Waiting for Meta approval  | ❌ No      |
| `REJECTED` | Meta rejected the template | ❌ No      |
| `DISABLED` | Disabled by you or Meta    | ❌ No      |

<Info>
  Only templates with `status: "APPROVED"` can be used to send messages. Check this field before attempting to send.
</Info>

## Template Categories

| Category         | Description           | Use Cases                                                  |
| ---------------- | --------------------- | ---------------------------------------------------------- |
| `UTILITY`        | Transactional updates | Order status, booking confirmations, account notifications |
| `AUTHENTICATION` | Security codes        | OTP, 2FA verification, password resets                     |
| `MARKETING`      | Promotional content   | Product launches, special offers, newsletters              |

## Quality Score

Meta assigns a quality score based on how users interact with your messages:

| Score     | Meaning        | Impact                 |
| --------- | -------------- | ---------------------- |
| `GREEN`   | High quality   | Full sending capacity  |
| `YELLOW`  | Medium quality | Monitoring required    |
| `RED`     | Low quality    | Reduced sending limits |
| `UNKNOWN` | Not yet rated  | New template           |

<Warning>
  Templates with `RED` quality scores may be paused or have limited sending capacity. Improve message quality to restore
  full access.
</Warning>

**Quality score can decline due to**:

* High block rates (users blocking your number)
* Low engagement (users not responding)
* Spam reports
* Irrelevant content

## Template Components

Templates consist of multiple components:

### Header

* **Optional** element at the top
* Can be: TEXT, IMAGE, VIDEO, or DOCUMENT
* Single variable allowed (for dynamic content)

### Body

* **Required** main message content
* Supports multiple variables (`{{1}}`, `{{2}}`, etc.)
* Maximum 1024 characters

### Footer

* **Optional** additional text at the bottom
* No variables allowed
* Often used for opt-out instructions

### Buttons

* **Optional** interactive elements
* Types: Call-to-action, Quick reply, URL
* Up to 3 buttons per template

## Use Cases

### Check Template Approval Status

Monitor when templates are approved:

```javascript theme={null}
async function waitForApproval(templateName) {
  const maxAttempts = 48; // Check for 48 hours
  const intervalHours = 1;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    const { data: templates } = await response.json();
    const template = templates.find((t) => t.name === templateName);

    if (template?.status === 'APPROVED') {
      console.log(`Template "${templateName}" is now approved!`);
      return true;
    } else if (template?.status === 'REJECTED') {
      console.error(`Template "${templateName}" was rejected`);
      return false;
    }

    // Wait 1 hour before checking again
    await new Promise((resolve) => setTimeout(resolve, intervalHours * 60 * 60 * 1000));
  }

  console.error('Template approval timeout');
  return false;
}
```

### Build Template Selector

Display only approved templates:

```javascript theme={null}
async function getApprovedTemplates() {
  const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const { data: templates } = await response.json();

  // Filter only approved templates
  return templates.filter((t) => t.status === 'APPROVED');
}

// Use in UI
const approvedTemplates = await getApprovedTemplates();
approvedTemplates.forEach((template) => {
  console.log(`${template.name} - ${template.category}`);
});
```

### Extract Template Variables

Parse template components to find required variables:

```javascript theme={null}
function getTemplateVariables(template) {
  const bodyComponent = template.components.find((c) => c.type === 'BODY');
  if (!bodyComponent) return [];

  // Extract {{1}}, {{2}}, etc.
  const matches = bodyComponent.text.match(/\{\{(\d+)\}\}/g);
  if (!matches) return [];

  return matches.map((m) => parseInt(m.match(/\d+/)[0]));
}

// Example usage
const template = templates.find((t) => t.name === 'order_confirmation');
const variables = getTemplateVariables(template);
console.log(`Template requires ${variables.length} variables:`, variables);
// Output: Template requires 2 variables: [1, 2]
```

## Filtering & Sorting (Coming Soon)

Future versions will support:

```bash theme={null}
# Filter by status
GET /api/templates/whatsapp?status=APPROVED

# Filter by category
GET /api/templates/whatsapp?category=UTILITY

# Sort by creation date
GET /api/templates/whatsapp?sort=-createdAt
```

## Template Languages

WhatsApp templates can be created in multiple languages:

```json theme={null}
{
  "name": "order_confirmation",
  "language": "en",
  "status": "APPROVED"
}
```

**Supported language codes**:

* `en` - English
* `it` - Italian
* `es` - Spanish
* `fr` - French
* `de` - German
* `pt` - Portuguese
* And 60+ more...

<Info>
  Create separate templates for each language you want to support. Use the same `name` with different `language` codes.
</Info>

## Common Errors

| Error                 | Cause                  | Solution                               |
| --------------------- | ---------------------- | -------------------------------------- |
| `unauthorized`        | Invalid API key        | Check Authorization header             |
| `no_whatsapp_account` | WhatsApp not connected | Connect WhatsApp in dashboard          |
| `rate_limit_exceeded` | Too many requests      | Implement caching, respect rate limits |

## Best Practices

<AccordionGroup>
  <Accordion title="Cache Template List">
    Templates don't change frequently. Cache the response:

    ```javascript theme={null}
    const CACHE_DURATION = 15 * 60 * 1000; // 15 minutes
    let templateCache = null;
    let cacheTime = 0;

    async function getTemplates() {
      if (templateCache && Date.now() - cacheTime < CACHE_DURATION) {
        return templateCache;
      }
      
      const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
        headers: { 'Authorization': `Bearer ${apiKey}` },
      });
      
      templateCache = await response.json();
      cacheTime = Date.now();
      
      return templateCache;
    }
    ```
  </Accordion>

  <Accordion title="Monitor Quality Scores">
    Regularly check template quality to prevent issues:

    ```javascript theme={null}
    async function checkTemplateHealth() {
      const { data: templates } = await getTemplates();
      
      const unhealthy = templates.filter(t => 
        t.qualityScore.score === 'RED' || t.qualityScore.score === 'YELLOW'
      );
      
      if (unhealthy.length > 0) {
        console.warn('Templates need attention:', unhealthy.map(t => t.name));
        // Send alert to team
      }
    }
    ```
  </Accordion>

  <Accordion title="Validate Before Sending">
    Always verify template is approved before sending:

    ```javascript theme={null}
    async function canSendTemplate(templateName) {
      const { data: templates } = await getTemplates();
      const template = templates.find(t => t.name === templateName);
      
      return template && template.status === 'APPROVED';
    }
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

* [Send WhatsApp Template](/api-reference/messaging-channels/whatsapp/send-template) - Send messages using templates


# Send WhatsApp Template
Source: https://docs.minimo.it/api-reference/messaging-channels/whatsapp/send-template

post /public/v1/templates/whatsapp/send
Send WhatsApp messages using Meta-approved templates

## Overview

Send WhatsApp messages to your contacts using pre-approved templates. Perfect for:

* **Transactional notifications**: Order updates, booking confirmations
* **Customer support**: Appointment reminders, service updates
* **Marketing messages**: Product launches, promotional offers (with opt-in)
* **Authentication**: OTP codes, verification messages

<Tip>
  Before sending messages, make sure to connect a WhatsApp Business Account by visiting the **Channels** section at
  [app.minimo.it/channels](https://app.minimo.it/channels).
</Tip>

## WhatsApp Template Requirements

Unlike emails, WhatsApp messages must use templates **approved by Meta** (Facebook). This ensures:

* User privacy and experience
* Compliance with WhatsApp Business Policy
* Reduced spam and unwanted messages

### Template Approval Process

1. **Create template** in Minimo dashboard
2. **Submit for approval** to Meta
3. **Wait 24-48 hours** for review
4. **Use approved template** via API

<Warning>
  Only templates with `status: "APPROVED"` can be used. Attempting to send with pending or rejected templates will fail.
</Warning>

## Template Categories

WhatsApp templates must be categorized:

| Category         | Description                   | Use Cases                          | 24h Window |
| ---------------- | ----------------------------- | ---------------------------------- | ---------- |
| `UTILITY`        | Account updates, transactions | Order status, booking confirmation | No         |
| `AUTHENTICATION` | OTP codes, verification       | 2FA codes, login verification      | No         |
| `MARKETING`      | Promotional content           | Product launch, special offers     | Yes\*      |

\*Marketing templates require user opt-in and are subject to the 24-hour messaging window.

## Phone Number Format

WhatsApp requires phone numbers in **E.164 format**:

```
+[country code][subscriber number]
```

**Examples**:

* ✅ `+393391234567` (Italy)
* ✅ `+12025551234` (US)
* ✅ `+447700900123` (UK)
* ❌ `3391234567` (missing country code)
* ❌ `+39 339 123 4567` (contains spaces)
* ❌ `+39-339-123-4567` (contains dashes)

<Info>
  Always validate and format phone numbers before sending. Invalid numbers will result in failed messages and count
  against your quality score.
</Info>

## Choosing the Sender (Multi-Number)

A company can connect **more than one WhatsApp number** (multi-sender / multi-WABA) — e.g.
a support line and a marketing line. Control which number a message is sent **from** with
the optional `sender` field:

* **Omit `sender`** → the message is sent from the company **preferred** number.
* **Set `sender`** → the message is sent from that number. Pass either the phone number
  (any formatting, e.g. `+39 351 1234567`) or the Meta `phone_number_id`.

```json theme={null}
{
  "recipient": "393391234567",
  "type": "template",
  "sender": "+393517654321",
  "template": {
    "name": "product_launch",
    "components": [
      { "type": "BODY", "parameters": [ { "type": "text", "text": "Jane" } ] }
    ]
  }
}
```

<Warning>
  An unknown or foreign `sender` returns `WHATSAPP_SENDER_NOT_FOUND`. Always source valid
  values from
  [List WhatsApp Senders](/api-reference/messaging-channels/whatsapp/list-senders).
</Warning>

<Note>
  When the `recipient` isn't a contact yet, this send creates one (marked "created via
  API"). Use the optional `contactSource` field to label where it came from (defaults to
  `WhatsApp`); existing contacts are never modified.
</Note>

## Template Variables

Templates support dynamic content through placeholders. Meta allows two placeholder styles, and the style is fixed when the template is created:

* **Positional**: numbered placeholders like `{{1}}`, `{{2}}`
* **Named**: descriptive placeholders like `{{customer_name}}`, `{{order_id}}`

### Positional Variables

**Template Example** (created in dashboard):

```
Hello {{1}}, your order {{2}} has been confirmed!

Total: {{3}}
Estimated delivery: {{4}}

Track your order: {{5}}
```

**API Request**:

```json theme={null}
{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          { "type": "text", "text": "Jane Doe" },
          { "type": "text", "text": "ORD-12345" },
          { "type": "text", "text": "$99.99" },
          { "type": "text", "text": "November 20, 2025" },
          { "type": "text", "text": "https://track.example.com/12345" }
        ]
      }
    ]
  }
}
```

<Note>
  Variable numbering starts at `{{1}}`, not `{{0}}`. Order matters - map parameters in the exact sequence defined in your template.
</Note>

<Info>
  Set `type` to `"template"` to send an approved template, or `"text"` (with a top-level
  `text` field) for a free-form session message. Component `type` values are uppercase:
  `HEADER`, `BODY`, `FOOTER`, `BUTTONS`. `companyId` is resolved from your API key — never
  send it in the body.
</Info>

### Named Variables

For templates with named placeholders, add `parameter_name` to each body parameter to state which placeholder the value fills:

**Template Example** (created in dashboard):

```
Hello {{customer_name}}, your order {{order_id}} has been confirmed!
```

**API Request**:

```json theme={null}
{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "order_confirmation_named",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          { "type": "text", "text": "Jane Doe", "parameter_name": "customer_name" },
          { "type": "text", "text": "ORD-12345", "parameter_name": "order_id" }
        ]
      }
    ]
  }
}
```

<Note>
  `parameter_name` is recommended but optional. If you omit it, Minimo resolves the names automatically from the approved template definition, matching your parameters **by position**: the first parameter fills the first placeholder appearing in the template body, and so on. When relying on this fallback, the order of your parameters must follow the order in which the placeholders appear in the template.
</Note>

<Warning>
  With explicit `parameter_name` values, every name must match a placeholder defined in the template — a wrong or missing name is rejected by Meta with `(#100) Invalid parameter`.
</Warning>

## WhatsApp Message Components

Templates can have multiple components:

### Header (Optional)

* Text, image, document, or video
* Single dynamic variable supported

### Body (Required)

* Main message content
* Supports multiple variables
* Maximum 1024 characters

### Footer (Optional)

* Additional info (e.g., "Reply STOP to opt-out")
* No variables allowed

### Buttons (Optional)

* Call-to-action buttons
* Quick reply buttons
* URL buttons with dynamic parameters

## Use Cases

<AccordionGroup>
  <Accordion title="Order Confirmation">
    Send instant confirmation when an order is placed:

    ```json theme={null}
    {
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "name": "order_confirmation",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              {"type": "text", "text": "Mario Rossi"},
              {"type": "text", "text": "ORD-789"},
              {"type": "text", "text": "€149.99"}
            ]
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Appointment Reminder">
    Remind customers about upcoming appointments:

    ```json theme={null}
    {
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "name": "appointment_reminder",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              {"type": "text", "text": "Dr. Smith"},
              {"type": "text", "text": "November 15, 2025"},
              {"type": "text", "text": "10:30 AM"},
              {"type": "text", "text": "Via Roma 123, Milano"}
            ]
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="OTP Verification">
    Send one-time passwords securely:

    ```json theme={null}
    {
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "name": "otp_code",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              {"type": "text", "text": "847592"},
              {"type": "text", "text": "5 minutes"}
            ]
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Shipping Update">
    Notify customers about delivery status:

    ```json theme={null}
    {
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "name": "shipping_update",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              {"type": "text", "text": "ORD-12345"},
              {"type": "text", "text": "Out for delivery"},
              {"type": "text", "text": "https://track.example.com/12345"}
            ]
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

### Message Quality Score

WhatsApp monitors your message quality. Maintain a high quality score by:

* ✅ Only sending to users who opted in
* ✅ Sending relevant, timely messages
* ✅ Using clear, professional language
* ✅ Respecting the 24-hour window for marketing
* ❌ Avoid spam-like behavior
* ❌ Don't send unsolicited messages
* ❌ Don't exceed rate limits

<Warning>
  Poor quality scores can result in: - Reduced sending limits - Template rejections - Account suspension
</Warning>

### Phone Number Validation

Always validate before sending:

```javascript theme={null}
function isValidE164(phone) {
  // Basic E.164 validation
  return /^\+[1-9]\d{1,14}$/.test(phone);
}

if (!isValidE164(phone)) {
  console.error('Invalid phone number format');
  return;
}
```

### Template Design Guidelines

* **Be concise**: Keep messages short and clear
* **Add context**: Include order numbers, dates, etc.
* **Include branding**: Mention your company name
* **Provide value**: Every message should be useful
* **Call-to-action**: Make next steps obvious

### Rate Limits & Messaging Tiers

WhatsApp enforces tiered messaging limits:

| Tier   | Daily Limit | How to Advance              |
| ------ | ----------- | --------------------------- |
| Tier 1 | 1,000       | Maintain quality score      |
| Tier 2 | 10,000      | Consistent quality + volume |
| Tier 3 | 100,000     | High quality + high volume  |
| Tier 4 | Unlimited   | Enterprise approval         |

Start at Tier 1, advance automatically with good performance.

## Common Errors

| Error                       | Cause                                      | Solution                                                                                                                |
| --------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `template_not_approved`     | Template pending/rejected                  | Check status in dashboard, resubmit if needed                                                                           |
| `invalid_phone_number`      | Phone not in E.164 format                  | Add country code, remove spaces/dashes                                                                                  |
| `template_not_found`        | Wrong template name                        | Verify template name in dashboard                                                                                       |
| `parameter_mismatch`        | Wrong number of variables                  | Match template variable count exactly                                                                                   |
| `(#100) Invalid parameter`  | Wrong `parameter_name` on a named template | Use the exact placeholder names defined in the template, or omit `parameter_name` and send parameters in template order |
| `rate_limit_exceeded`       | Messaging tier limit reached               | Wait for reset or request tier upgrade                                                                                  |
| `recipient_not_on_whatsapp` | Phone number not on WhatsApp               | Verify number is active on WhatsApp                                                                                     |

## Tracking & Analytics

Monitor message delivery and engagement:

* **Delivery status**: Sent, delivered, read
* **Failure reasons**: Why messages didn't deliver
* **Response rate**: How many users reply

Access analytics via the Minimo dashboard.

## 24-Hour Messaging Window

### For Marketing Templates

After a user-initiated conversation, you have a **24-hour window** to send marketing messages without requiring a new opt-in.

**User-initiated means**:

* User sends a message to your WhatsApp number
* User clicks a WhatsApp link
* User interacts with your WhatsApp ad

**Outside the 24-hour window**: Only UTILITY and AUTHENTICATION templates can be sent.

<Info>
  UTILITY templates (order confirmations, booking updates) can be sent anytime, regardless of the 24-hour window.
</Info>

## Compliance & Opt-In

### User Consent Required

* Get explicit opt-in before sending WhatsApp messages
* Keep records of consent
* Honor opt-out requests immediately
* Follow GDPR and local privacy regulations

### Opt-Out Handling

Include opt-out instructions in templates:

```
Don't want to receive these messages? Reply STOP to opt out.
```

## Related Endpoints

* [List WhatsApp Senders](/api-reference/messaging-channels/whatsapp/list-senders) - Connected numbers you can send `sender` from
* [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates) - View all available templates
* [Inbound & Webhooks](/api-reference/messaging-channels/whatsapp/inbound-webhooks) - How replies and template-status updates arrive


# Authentication & API Keys
Source: https://docs.minimo.it/api-reference/overview/authentication

Learn how to authenticate with the Minimo API using API keys

## Overview

The Minimo API uses **API keys** for authentication. All API requests must include a valid API key in the `Authorization` header using the Bearer token scheme.

## Creating an API Key

<Steps>
  <Step title="Navigate to API Key Section">
    Go to your [Minimo Account Settings](https://app.minimo.it/account) and select the **API Key** tab.
  </Step>

  <Step title="Create New API Key">Click the **"+ Create new API key"** button.</Step>

  <Step title="Configure Your Key">
    Provide the following information: - **Name**: A descriptive name to identify this key (e.g., "Production App",
    "Staging Environment") - **Permissions**: Select which API resources this key can access - **Expiration**: Set an
    expiration date (recommended: 1 year maximum)
  </Step>

  <Step title="Save and Copy">
    After creating the key, **copy it immediately** and store it securely. For security reasons, you won't be able to
    see the full key again.
  </Step>
</Steps>

<Warning>
  API keys are sensitive credentials. Treat them like passwords and never commit them to public repositories or share
  them publicly.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example Request (cURL)

```bash theme={null}
curl https://api.minimo.it/public/v1/contacts \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  }'
```

### Example Request (JavaScript)

```javascript theme={null}
const response = await fetch('https://api.minimo.it/public/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mn-abc123-xyz789',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  }),
});

const data = await response.json();
console.log(data);
```

### Example Request (Python)

```python theme={null}
import requests

url = "https://api.minimo.it/public/v1/contacts"
headers = {
    "Authorization": "Bearer mn-abc123-xyz789",
    "Content-Type": "application/json"
}
payload = {
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

## API Key Format

Minimo API keys follow this format:

```
mn-{CLIENT_ID}-{SECRET_KEY}
```

**Example**: `mn-abc123-xyz789def456ghi789`

* `mn-` prefix identifies it as a Minimo key
* `CLIENT_ID` identifies your Minimo account
* `SECRET_KEY` is the secure token

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Separate Keys for Different Environments">
    Create different API keys for development, staging, and production. This allows you to: - Rotate keys without
    affecting all environments - Track usage per environment - Revoke compromised keys without downtime
  </Accordion>

  <Accordion title="Set Appropriate Permissions">
    Grant each API key only the permissions it needs: - Read-only keys for analytics dashboards - Write-only keys for
    contact imports - Full access only when necessary
  </Accordion>

  <Accordion title="Rotate Keys Regularly">
    Set expiration dates and rotate your API keys at least annually. This limits the impact of leaked credentials.
  </Accordion>

  <Accordion title="Store Keys Securely">
    * Use environment variables in your application - Store in secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)
    * Never hardcode keys in your source code - Never commit keys to version control
  </Accordion>

  <Accordion title="Monitor Usage">
    Regularly review API key usage in your Minimo dashboard to detect: - Unusual request patterns - Unauthorized access
    attempts - Performance issues
  </Accordion>
</AccordionGroup>

## Authentication Errors

### 401 Unauthorized

**Cause**: Missing or invalid API key

**Response Example**:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
```

**Solution**: Verify your API key is correct and included in the `Authorization` header.

### 403 Forbidden

**Cause**: API key lacks required permissions

**Response Example**:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have permission to access this resource"
  }
}
```

**Solution**: Update the API key permissions in your Minimo dashboard or create a new key with appropriate access.

### 429 Too Many Requests

**Cause**: Rate limit exceeded

**Response Example**:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}
```

**Solution**: Implement exponential backoff and respect rate limits. Check the `X-RateLimit-*` headers in responses.

## Client-Side vs. Server-Side Usage

### Server-Side (Recommended) ✅

API keys should primarily be used in server-side applications where they can be kept secure:

* Backend APIs
* Server-side scripts
* Scheduled jobs/cron tasks
* Server-to-server integrations

### Client-Side (Use with Caution) ⚠️

While technically possible, using API keys client-side (browser, mobile apps) exposes them to users. If you must use keys client-side:

1. Create a **separate API key** with **read-only permissions**
2. Limit permissions to only what's needed (e.g., "Create Contact" only)
3. Set short expiration periods
4. Monitor usage closely

<Warning>
  For sensitive operations (sending messages, accessing analytics), always use server-side authentication.
</Warning>

## Revoking an API Key

If a key is compromised or no longer needed:

1. Go to [Account Settings](https://app.minimo.it/account) → **API Keys**
2. Find the key in the list
3. Click **Revoke** or **Delete**
4. Confirm the action

<Info>Revoked keys stop working immediately. Update your applications before revoking keys used in production.</Info>

## Need Help?

If you have questions about authentication or API key management:

* Email: [info@minimo.it](mailto:info@minimo.it)
* Dashboard: [app.minimo.it/account](https://app.minimo.it/account)


# API Conventions
Source: https://docs.minimo.it/api-reference/overview/conventions

Understand Minimo API structure, response formats, and common patterns

## Base URL

The Minimo API is served from two base URLs, depending on the endpoint:

| Server         | Base URL                | Endpoints                                          |
| -------------- | ----------------------- | -------------------------------------------------- |
| **New API**    | `https://api.minimo.it` | Contacts, WhatsApp, Custom Fields, Email Templates |
| **Legacy API** | `https://app.minimo.it` | Messages, Campaigns                                |

**Example Endpoints**:

```
POST https://api.minimo.it/public/v1/contacts
GET  https://api.minimo.it/public/v1/templates/whatsapp
GET  https://api.minimo.it/public/v1/templates/email
```

<Info>All requests must use HTTPS. HTTP requests will be rejected.</Info>

<Note>
  New endpoints are being progressively migrated to `api.minimo.it`. Each endpoint's documentation page specifies the
  correct base URL.
</Note>

## Request Format

### Content Type

All POST, PUT, and PATCH requests must include the `Content-Type` header:

```bash theme={null}
Content-Type: application/json
```

### Request Body

Request bodies should be valid JSON:

```json theme={null}
{
  "email": "customer@example.com",
  "firstName": "Jane",
  "customFields": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}
```

## Response Format

### Success Response

Successful requests return appropriate HTTP status codes and JSON responses:

**Example (200 OK)**:

```json theme={null}
{
  "id": "cnt_abc123",
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "createdAt": "2025-11-13T10:30:00Z",
  "updatedAt": "2025-11-13T10:30:00Z"
}
```

### Error Response

Errors return a consistent structure:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid email address format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}
```

**Error Object Fields**:

* `code`: Machine-readable error identifier
* `message`: Human-readable error description
* `details`: Additional context (optional)

## HTTP Status Codes

The Minimo API uses standard HTTP status codes:

| Code  | Meaning               | Description                          |
| ----- | --------------------- | ------------------------------------ |
| `200` | OK                    | Request succeeded                    |
| `201` | Created               | Resource successfully created        |
| `400` | Bad Request           | Invalid request format or parameters |
| `401` | Unauthorized          | Missing or invalid API key           |
| `403` | Forbidden             | API key lacks required permissions   |
| `404` | Not Found             | Resource doesn't exist               |
| `422` | Unprocessable Entity  | Validation error (invalid data)      |
| `429` | Too Many Requests     | Rate limit exceeded                  |
| `500` | Internal Server Error | Server error (contact support)       |
| `503` | Service Unavailable   | Temporary service disruption         |

## Common Error Codes

| Error Code              | HTTP Status | Description                            |
| ----------------------- | ----------- | -------------------------------------- |
| `unauthorized`          | 401         | Invalid or missing API key             |
| `forbidden`             | 403         | Insufficient permissions               |
| `not_found`             | 404         | Resource not found                     |
| `validation_error`      | 422         | Invalid input data                     |
| `rate_limit_exceeded`   | 429         | Too many requests                      |
| `template_not_approved` | 422         | WhatsApp template not approved by Meta |
| `invalid_phone_number`  | 422         | Phone number format invalid            |
| `duplicate_resource`    | 409         | Resource already exists                |

## Pagination

List endpoints support pagination using query parameters:

### Parameters

* `page`: Page number (default: `1`)
* `limit`: Items per page (default: `25`, max: `100`)

### Example Request

```bash theme={null}
GET /v1/contacts?page=2&limit=50
```

### Response Structure

```json theme={null}
{
  "data": [
    { "id": "cnt_1", "email": "user1@example.com" },
    { "id": "cnt_2", "email": "user2@example.com" }
  ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 150,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": true
  }
}
```

**Pagination Fields**:

* `page`: Current page number
* `limit`: Items per page
* `total`: Total number of items
* `totalPages`: Total number of pages
* `hasNext`: Whether there's a next page
* `hasPrevious`: Whether there's a previous page

## Filtering & Sorting

### Filtering (Coming Soon)

Some endpoints support filtering using query parameters:

```bash theme={null}
GET /v1/contacts?tag=vip&status=active
```

### Sorting (Coming Soon)

Use the `sort` parameter to order results:

```bash theme={null}
GET /v1/contacts?sort=-createdAt
# - prefix for descending, + or no prefix for ascending
```

## Timestamps

All timestamps are returned in ISO 8601 format (UTC):

```json theme={null}
{
  "createdAt": "2025-11-13T10:30:00Z",
  "updatedAt": "2025-11-13T14:45:30Z"
}
```

## Idempotency

Some endpoints support idempotency keys to prevent duplicate operations:

```bash theme={null}
POST /v1/contacts
Idempotency-Key: unique-key-12345
```

<Tip>Use idempotency keys when retrying failed requests to avoid creating duplicates.</Tip>

## Rate Limiting

### Headers

All responses include rate limit information:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699889400
```

* `X-RateLimit-Limit`: Maximum requests per window
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: Unix timestamp when limit resets

### Handling Rate Limits

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}
```

**Best Practices**:

1. Monitor `X-RateLimit-Remaining` header
2. Implement exponential backoff
3. Respect the `Retry-After` header value
4. Cache responses when possible

## Versioning

The current API version is **v1**.

* **New API** (`api.minimo.it`): The version prefix `/v1/` is **required** in all paths.
* **Legacy API** (`app.minimo.it`): Paths use the `/api/` prefix without version number.

```
# New API - version prefix required
POST https://api.minimo.it/public/v1/contacts

# Legacy API - no version prefix
POST https://app.minimo.it/api/transactionals
```

## CORS (Cross-Origin Requests)

The Minimo API supports CORS for client-side requests. However, we recommend making API calls from your server to keep API keys secure.

Allowed origins are configurable per API key in your dashboard settings.

## Webhooks

Minimo can forward real-time WhatsApp events — inbound replies, delivery events and template-status
updates — to your backend. See [Inbound & webhooks](/api-reference/messaging-channels/whatsapp/inbound-webhooks).

Event notifications for other channels (email delivered/failed, contact created/updated) are being
rolled out; this page will list them as they ship.

## Testing

### Test Mode (Coming Soon)

Use test mode to experiment without affecting production data:

```bash theme={null}
Authorization: Bearer mn-test-abc123-xyz789
```

Test API keys start with `mn-test-` prefix.

## Need Help?

If you encounter unexpected behavior or have questions about API conventions:

* Email: [info@minimo.it](mailto:info@minimo.it)
* Check [API Status](https://status.minimo.it) for known issues


# Introduction
Source: https://docs.minimo.it/api-reference/overview/introduction

Welcome to the Minimo API - Build powerful messaging and CRM integrations

## What is the Minimo API?

The Minimo API is a RESTful API that allows you to integrate Minimo's messaging and contact management capabilities into your applications, websites, and workflows.

With the Minimo API, you can:

* **Manage contacts**: Create, update, and organize your contact database
* **Send messages**: Deliver emails and WhatsApp messages using approved templates
* **Track engagement**: Access message delivery statistics and analytics
* **Automate workflows**: Integrate with your existing systems and tools

## Who should use this API?

The Minimo API is designed for:

* **Developers** building custom integrations with Minimo
* **Product teams** embedding messaging capabilities into their applications
* **Technical users** automating contact management and messaging workflows
* **Agencies** managing multiple clients and campaigns programmatically

## API vs. Integrations

* **Use the API** when you want to build custom integrations, make direct HTTP requests, or have full programmatic control
* **Use Integrations** (Zapier, ActiveCampaign, etc.) for no-code/low-code automation between Minimo and other platforms

<Tip>
  If you prefer no-code solutions, check out our [Integrations & Apps](/product/introduction) section for ready-made
  connectors.
</Tip>

## Getting Started

Ready to start building? Follow these steps:

<Steps>
  <Step title="Create an API Key">
    Generate your API key in the Minimo dashboard under [Account Settings](https://app.minimo.it/account). Learn more in
    [Authentication & API Keys](/api-reference/overview/authentication).
  </Step>

  <Step title="Review API Conventions">
    Understand our API structure, error handling, and response formats. See [API
    Conventions](/api-reference/overview/conventions).
  </Step>

  <Step title="Make Your First Request">
    Start with a simple contact creation or template send. Browse available endpoints in the sidebar →
  </Step>
</Steps>

## API Architecture

The Minimo API is organized into logical sections:

### Core Data

Manage the foundational data objects like contacts, custom fields, and segments.

**Example**: Create or update a contact with custom attributes.

### Messaging Channels

Send messages through different channels (Email, WhatsApp) using approved templates.

**Example**: Send a WhatsApp notification or transactional email.

### Legacy

Deprecated endpoints maintained for backward compatibility. **Use the new endpoints instead.**

## Support & Resources

<CardGroup>
  <Card title="API Status" icon="signal" href="https://status.minimo.it">
    Check real-time API uptime and performance
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:info@minimo.it">
    Get help from our technical team
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://app.minimo.it">
    Manage API keys and view analytics
  </Card>
</CardGroup>

## Rate Limits & Fair Use

All API endpoints are rate-limited to ensure service quality for all users. Current limits:

* **Standard Plan**: 100 requests per minute
* **Pro Plan**: 500 requests per minute
* **Enterprise**: Custom limits available

<Info>
  Rate limit details are returned in response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
  `X-RateLimit-Reset`.
</Info>

Contact our team at [info@minimo.it](mailto:info@minimo.it) if you need higher limits.


# Contact Sync
Source: https://docs.minimo.it/guides/ai-prompts/contact-sync

AI-ready prompt to sync your user database with Minimo contacts, including custom field creation and upsert

Give this prompt to your AI coding tool (Lovable, V0, Replit, Cursor, Claude) to automatically build a contact sync integration with Minimo.

<Tip>
  You can copy the entire prompt from the [Full Prompt](#full-prompt) section at the bottom of this page and paste it
  directly into your AI tool.
</Tip>

<Warning>
  **Using PostgreSQL or Supabase?** If your application runs on a PostgreSQL database (including Supabase), we strongly
  recommend using the [native Supabase Connection](/product/data-sync/supabase) instead of this API-based sync. The
  native connection is plug-and-play: it reads your data directly from the database in read-only mode, requires zero
  extra code, has no API failure points, and your data stays entirely in your infrastructure.
</Warning>

***

## What This Prompt Does

When given to an AI coding assistant, it will implement:

1. **A reusable Minimo API client** with authentication
2. **Custom field setup** that runs on app startup to ensure all required fields exist
3. **Contact upsert** on every user create/update to keep Minimo in sync
4. **Contact deletion** when users are removed

***

## Prerequisites

Before using this prompt, you need:

* A Minimo account with API access
* An API key (see [Authentication](/api-reference/overview/authentication))

***

## API Endpoints Used

This integration uses the following endpoints:

| Endpoint                                                                                  | Purpose                         |
| ----------------------------------------------------------------------------------------- | ------------------------------- |
| [GET /public/v1/custom-fields](/api-reference/core-data/custom-fields/list)               | List existing custom fields     |
| [POST /public/v1/custom-fields](/api-reference/core-data/custom-fields/create)            | Create missing custom fields    |
| [POST /public/v1/contacts](/api-reference/core-data/contacts/upsert)                      | Create or update a contact      |
| [GET /public/v1/contacts/by-email/:email](/api-reference/core-data/contacts/get-by-email) | Look up a contact by email      |
| [PUT /public/v1/contacts/:id](/api-reference/core-data/contacts/update-by-id)             | Update a specific contact by ID |
| [DELETE /public/v1/contacts/:id](/api-reference/core-data/contacts/delete)                | Soft-delete a contact           |

***

## Authentication

All requests require the API key in the `Authorization` header:

```
Authorization: Bearer mn-{clientId}-{apiKey}
```

The company is automatically identified from your API key — no additional headers needed.

<Warning>Never expose your API key in client-side code. Always call Minimo APIs from your backend.</Warning>

***

## How Contact Matching Works

The upsert endpoint matches contacts in this order:

<Steps>
  <Step title="Match by email">
    If `email` is provided, searches for an existing contact with the same email in your company.
  </Step>

  <Step title="Match by phone">If no email match is found and `phone` is provided, searches by phone number.</Step>
  <Step title="Create new">If no match is found, creates a new contact.</Step>
</Steps>

<Info>
  **Custom fields are merged on update**: existing values not included in the request are preserved. Only the keys you
  send are overwritten.
</Info>

<Tip>
  **Need to update a contact's email?** Use [GET
  /public/v1/contacts/by-email/:email](/api-reference/core-data/contacts/get-by-email) to find the contact ID, then [PUT
  /public/v1/contacts/:id](/api-reference/core-data/contacts/update-by-id) to update it. The upsert endpoint matches by
  email first, so changing it would create a duplicate unless a phone number is also provided.
</Tip>

***

## Key Behaviors

<AccordionGroup>
  <Accordion title="Default system fields">
    `FIRST_NAME` and `LAST_NAME` are created automatically for every Minimo company. You don't need to create them — just include their values in the `customFields` object.
  </Accordion>

  <Accordion title="Custom field keys are uppercase">
    Field keys are normalized to uppercase internally. Always use uppercase keys like `PLAN_TYPE`, not `planType`.
  </Accordion>

  <Accordion title="Empty strings become null">
    Sending `""` for `email` or `phone` is treated as `null`. Sending `null` for a field on update preserves the existing
    value.
  </Accordion>

  <Accordion title="Status is free-form">
    The `status` field accepts any string (e.g., `active`, `churned`, `trial`). There is no predefined list.
  </Accordion>

  <Accordion title="Custom field types">
    Supported types: `text`, `number`, `boolean`, `date`, `datetime`, `time`, `json`.
  </Accordion>
</AccordionGroup>

***

## Quick Example

### Create a custom field

```bash theme={null}
curl -X POST "https://api.minimo.it/public/v1/custom-fields" \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PLAN_TYPE",
    "displayName": "Plan Type",
    "type": "text",
    "category": "Subscription",
    "source": "External",
    "visibility": true
  }'
```

### Upsert a contact

```bash theme={null}
curl -X POST "https://api.minimo.it/public/v1/contacts" \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "phone": "+393391234567",
    "status": "active",
    "source": "webapp",
    "customFields": {
      "FIRST_NAME": "John",
      "LAST_NAME": "Doe",
      "PLAN_TYPE": "pro"
    },
    "externalId": "usr_abc123"
  }'
```

**Response:**

```json theme={null}
{
  "id": 123,
  "phone": "+393391234567"
}
```

***

## Full Prompt

Copy the prompt below and paste it into your AI coding tool.

````markdown theme={null}
# Minimo Contact Sync Integration

You are an AI coding assistant. Your task is to implement a contact synchronization integration between the user's application and **Minimo**, a customer engagement platform. The integration must keep the user database synchronized with Minimo contacts via Minimo's public REST APIs.

Every time a user is created, updated, or has any field changed in the application, the corresponding contact in Minimo must be created or updated. If the application tracks custom user attributes (e.g., plan type, signup date, company name), those must also be synced as custom fields.

---

## 1. Authentication

All API requests require the API key in the `Authorization` header. The company is automatically identified from your API key.

| Header          | Value                           | Description                |
| --------------- | ------------------------------- | -------------------------- |
| `Authorization` | `Bearer mn-{clientId}-{apiKey}` | API key provided by Minimo |

Store these as environment variables:

```
MINIMO_API_URL=https://api.minimo.it
MINIMO_API_KEY=mn-abc123-xyz789
```

Every request must include the Authorization header. Example:

```
Authorization: Bearer mn-abc123-xyz789
Content-Type: application/json
```

---

## 2. API Reference

### 2.1 List Custom Fields

Retrieve all custom fields defined for the company.

```
GET /public/v1/custom-fields
```

**Query Parameters:**

| Parameter | Type     | Required | Description                                       |
| --------- | -------- | -------- | ------------------------------------------------- |
| `groupBy` | `string` | No       | Pass `category` to get fields grouped by category |

**Response (flat):** `CustomField[]`

**Response (grouped, `?groupBy=category`):**

```json
{
  "groups": [
    {
      "category": "Personal Info",
      "fields": [
        {
          "id": 1,
          "key": "FIRST_NAME",
          "displayName": "First name",
          "type": "text",
          "category": "Personal Info",
          "source": "System",
          "visibility": true
        }
      ]
    }
  ],
  "total": 5
}
```

**cURL Example:**

```bash
curl -X GET "${MINIMO_API_URL}/public/v1/custom-fields" \
  -H "Authorization: Bearer ${MINIMO_API_KEY}"
```

---

### 2.2 Create Custom Field

Create a new custom field definition.

```
POST /public/v1/custom-fields
```

**Request Body:**

| Field              | Type      | Required | Description                                                             |
| ------------------ | --------- | -------- | ----------------------------------------------------------------------- |
| `key`              | `string`  | Yes      | Unique identifier (uppercase recommended, e.g., `PLAN_TYPE`)            |
| `displayName`      | `string`  | Yes      | Human-readable label (e.g., `Plan Type`)                                |
| `type`             | `string`  | Yes      | One of: `text`, `number`, `boolean`, `date`, `datetime`, `time`, `json` |
| `category`         | `string`  | No       | Group label (e.g., `Subscription Info`)                                 |
| `acceptableValues` | `object`  | No       | For select/enum fields, the allowed values                              |
| `source`           | `string`  | No       | `Manual` (default), `System`, or `External`                             |
| `visibility`       | `boolean` | No       | Whether the field is visible in UI (default: `false`)                   |

**Response:** The created `CustomField` object.

**cURL Example:**

```bash
curl -X POST "${MINIMO_API_URL}/public/v1/custom-fields" \
  -H "Authorization: Bearer ${MINIMO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PLAN_TYPE",
    "displayName": "Plan Type",
    "type": "text",
    "category": "Subscription",
    "source": "External",
    "visibility": true
  }'
```

---

### 2.3 Upsert Contact

Create a new contact or update an existing one. This is the primary endpoint for syncing users.

```
POST /public/v1/contacts
```

**Request Body:**

| Field                  | Type     | Required | Description                                         |
| ---------------------- | -------- | -------- | --------------------------------------------------- |
| `email`                | `string` | No\*     | Contact email (must be valid email format)          |
| `phone`                | `string` | No\*     | Contact phone number                                |
| `status`               | `string` | No       | Any string status value (e.g., `active`, `churned`) |
| `source`               | `string` | No       | Source identifier (e.g., `webapp`, `api`)           |
| `customFields`         | `object` | No       | Key-value map of custom field values                |
| `externalId`           | `string` | No       | Your application's user ID                          |
| `externalConnectionId` | `string` | No       | Connection/integration identifier                   |

\*At least `email` or `phone` should be provided for matching.

**Matching Logic:**

1. First, tries to find an existing contact by **email** (within the same company)
2. If no email match, tries to find by **phone**
3. If no match found, creates a new contact

**Update Behavior:**

- Only provided fields are updated; `null`/missing fields preserve existing values
- **Custom fields are merged**: existing custom field values are preserved, provided values override

**Response:**

```json
{
  "id": 123,
  "phone": "+1234567890"
}
```

**cURL Example:**

```bash
curl -X POST "${MINIMO_API_URL}/public/v1/contacts" \
  -H "Authorization: Bearer ${MINIMO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "phone": "+1234567890",
    "status": "active",
    "source": "webapp",
    "customFields": {
      "FIRST_NAME": "John",
      "LAST_NAME": "Doe",
      "PLAN_TYPE": "pro",
      "SIGNUP_DATE": "2025-01-15"
    },
    "externalId": "usr_abc123"
  }'
```

---

### 2.4 Delete Contact

Soft-delete a contact by ID.

```
DELETE /public/v1/contacts/{id}
```

**Path Parameters:**

| Parameter | Type     | Description                                             |
| --------- | -------- | ------------------------------------------------------- |
| `id`      | `number` | The Minimo contact ID (returned by the upsert endpoint) |

**Response:** `true` on success.

**cURL Example:**

```bash
curl -X DELETE "${MINIMO_API_URL}/public/v1/contacts/123" \
  -H "Authorization: Bearer ${MINIMO_API_KEY}"
```

---

## 3. Integration Steps

Follow these steps to implement the full contact sync:

### Step 1: Create a Minimo API Client

Create a reusable HTTP client module that attaches the authentication headers to every request.

```typescript
// Example: lib/minimo.ts

const MINIMO_API_URL = process.env.MINIMO_API_URL!;
const MINIMO_API_KEY = process.env.MINIMO_API_KEY!;

async function minimoRequest(method: string, path: string, body?: unknown) {
  const response = await fetch(`${MINIMO_API_URL}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${MINIMO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(`Minimo API error ${response.status}: ${JSON.stringify(error)}`);
  }

  return response.json();
}
```

### Step 2: Ensure Custom Fields Exist

Before syncing contacts, check that all required custom fields are defined in Minimo. Create any missing ones.

```typescript
interface CustomFieldDefinition {
  key: string;
  displayName: string;
  type: 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'time' | 'json';
  category?: string;
}

// Define the custom fields your application needs
const REQUIRED_FIELDS: CustomFieldDefinition[] = [
  { key: 'PLAN_TYPE', displayName: 'Plan Type', type: 'text', category: 'Subscription' },
  { key: 'SIGNUP_DATE', displayName: 'Signup Date', type: 'date', category: 'Account' },
  { key: 'COMPANY_NAME', displayName: 'Company Name', type: 'text', category: 'Company Info' },
  { key: 'IS_PAYING', displayName: 'Is Paying', type: 'boolean', category: 'Subscription' },
  // Add more fields as needed based on your user model
];

async function ensureCustomFieldsExist() {
  // Get existing fields
  const existingFields = await minimoRequest('GET', '/public/v1/custom-fields');
  const existingKeys = new Set(existingFields.map((f: { key: string }) => f.key));

  // Create missing fields
  for (const field of REQUIRED_FIELDS) {
    if (!existingKeys.has(field.key)) {
      await minimoRequest('POST', '/public/v1/custom-fields', {
        key: field.key,
        displayName: field.displayName,
        type: field.type,
        category: field.category,
        source: 'External',
        visibility: true,
      });
    }
  }
}
```

### Step 3: Map User Fields to Minimo Contact

Create a mapping function that transforms your user model into a Minimo upsert payload.

```typescript
// Adapt this to your user model
interface AppUser {
  id: string;
  email: string;
  phone?: string;
  firstName?: string;
  lastName?: string;
  plan?: string;
  signupDate?: Date;
  companyName?: string;
  isPaying?: boolean;
}

function mapUserToMinimoContact(user: AppUser) {
  return {
    email: user.email,
    phone: user.phone ?? undefined,
    status: 'active',
    source: 'webapp',
    externalId: user.id,
    customFields: {
      // FIRST_NAME and LAST_NAME are default system fields (already exist)
      FIRST_NAME: user.firstName ?? '',
      LAST_NAME: user.lastName ?? '',
      // Custom fields (must be created via Step 2)
      PLAN_TYPE: user.plan ?? '',
      SIGNUP_DATE: user.signupDate?.toISOString().split('T')[0] ?? '',
      COMPANY_NAME: user.companyName ?? '',
      IS_PAYING: user.isPaying ?? false,
    },
  };
}
```

### Step 4: Sync on Every User Change

Call the upsert endpoint whenever a user is created or updated.

```typescript
async function syncUserToMinimo(user: AppUser) {
  const payload = mapUserToMinimoContact(user);
  return minimoRequest('POST', '/public/v1/contacts', payload);
}
```

Integrate this into your application's user lifecycle:

```typescript
// On user creation
async function createUser(userData: CreateUserInput) {
  const user = await db.users.create(userData);
  await syncUserToMinimo(user);
  return user;
}

// On user update
async function updateUser(userId: string, updates: Partial<AppUser>) {
  const user = await db.users.update(userId, updates);
  await syncUserToMinimo(user);
  return user;
}

// On user deletion (optional)
async function deleteUser(userId: string) {
  const user = await db.users.findById(userId);
  if (user.minimoContactId) {
    await minimoRequest('DELETE', `/public/v1/contacts/${user.minimoContactId}`);
  }
  await db.users.delete(userId);
}
```

### Step 5: Run Field Setup on App Startup

Ensure custom fields exist when the application starts:

```typescript
// In your app initialization
async function initializeMinimo() {
  try {
    await ensureCustomFieldsExist();
    console.log('Minimo custom fields initialized');
  } catch (error) {
    console.error('Failed to initialize Minimo fields:', error);
  }
}
```

---

## 4. Important Behaviors

### Contact Matching

- **Email has priority**: if both email and phone are provided, matching is done by email first
- **Phone fallback**: phone is only used for matching if email is not provided or no email match is found
- **Company-scoped**: matching only considers contacts within your company

### Custom Fields

- **Merge on update**: when updating an existing contact, custom fields are merged. Existing values not included in the request are preserved. Only provided keys are overwritten.
- **Replace on create**: when creating a new contact, only the provided custom fields are stored.
- **Keys are uppercase**: custom field keys are normalized to uppercase internally (use uppercase keys like `PLAN_TYPE`).
- **Default system fields**: `FIRST_NAME` and `LAST_NAME` are created automatically for every company. You do not need to create them; just include their values in `customFields`.

### Value Handling

- **Empty strings become null**: if you send `""` for email or phone, it is treated as `null`
- **Null fields are ignored on update**: sending `null` for a field preserves the existing value
- **Status is free-form**: the `status` field accepts any string, there is no predefined enum

### Error Responses

- **401 Unauthorized**: invalid API key or missing headers
- **400 Bad Request**: validation error (e.g., invalid email format)
- **500 Internal Server Error**: server-side issue, retry with exponential backoff

---

## 5. Environment Variables Checklist

Add these to your `.env` file:

```
MINIMO_API_URL=https://api.minimo.it
MINIMO_API_KEY=        # Format: mn-{clientId}-{apiKey}
```

---

## 6. Summary

| What                  | When                    | API Endpoint                      |
| --------------------- | ----------------------- | --------------------------------- |
| Create custom fields  | App startup (once)      | `POST /public/v1/custom-fields`   |
| Check existing fields | App startup (once)      | `GET /public/v1/custom-fields`    |
| Sync user to Minimo   | User created or updated | `POST /public/v1/contacts`        |
| Remove from Minimo    | User deleted            | `DELETE /public/v1/contacts/{id}` |
````


# Connect your agent (MCP)
Source: https://docs.minimo.it/guides/connect-your-agent

Drive Minimo from Claude, Cursor, ChatGPT or any MCP client

## Overview

Minimo is exposed as an **MCP server** (Model Context Protocol). Once connected, your AI agent can read and act on your workspace — contacts, segments, email & WhatsApp templates, campaigns, automations and connection status — through Mo's tools.

The endpoint is `https://api.minimo.it/mcp` (Streamable HTTP).

Most clients — Claude, ChatGPT, Cursor — **don't need an API key**: point them at the URL and they discover the Minimo sign-in automatically (OAuth). You just click **Authorize**.

For scripts, automations and clients that can't run a sign-in flow, use an **API key**: an `mn-…` key with the **MCP (AI agent)** permission (`mcp:invoke`), sent as a Bearer token in the `Authorization` header.

<Tip>
  Want your agent to set this up itself? Point it at the [agent-setup instructions](/agent-setup) — a single prompt that
  installs the connection for you.
</Tip>

## Get an API key

<Steps>
  <Step title="From the dashboard (fastest)">
    In **Settings → Mo & MCP**, the **"Use Mo everywhere"** card shows your key already generated — copy it straight
    from the input. It's scoped to MCP only and valid for 1 year.
  </Step>

  <Step title="Or from Developer settings">
    Go to **Developer → API keys**, create a new key and select the **MCP (AI agent)** permission.
  </Step>

  <Step title="Copy it immediately">
    The key is shown **once**. Store it securely — you won't be able to see it again.
  </Step>
</Steps>

<Warning>
  API keys are sensitive credentials. Treat them like passwords and never commit them to public repositories.
</Warning>

## Claude (claude.ai)

<Steps>
  <Step title="Add the custom connector">
    Open [Claude → Settings → Connectors](https://claude.ai/customize/connectors) and click **Add custom connector**.
    Name it `Minimo` and set the URL to `https://api.minimo.it/mcp`.
  </Step>

  <Step title="Authorize">
    Press **Add**, then **Connect** — a Minimo window opens; click **Authorize**. No key to copy.
  </Step>
</Steps>

## Claude Code (CLI)

```bash theme={null}
claude mcp add --transport http minimo https://api.minimo.it/mcp
```

When prompted, click **Authorize** in the browser. For headless / CI use, pass a key instead:

```bash theme={null}
claude mcp add --transport http minimo https://api.minimo.it/mcp \
  --header "Authorization: Bearer mn-YOUR-API-KEY"
```

## Cursor

Add Minimo to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json theme={null}
{
  "mcpServers": {
    "minimo": {
      "url": "https://api.minimo.it/mcp"
    }
  }
}
```

Reload Cursor and click **Authorize** when Minimo asks. For headless use, add the key header instead:

```json theme={null}
{
  "mcpServers": {
    "minimo": {
      "url": "https://api.minimo.it/mcp",
      "headers": {
        "Authorization": "Bearer mn-YOUR-API-KEY"
      }
    }
  }
}
```

## ChatGPT

Open [ChatGPT → Settings → Apps & Connectors](https://chatgpt.com/#settings/Connectors), enable **Developer mode** (Plus/Pro/Enterprise), click **Add connector** with the Minimo MCP URL, set authentication to **OAuth** and click **Authorize** in the Minimo window.

## Try it

Paste this into your connected agent — it's read-only and proves the connection end-to-end:

```text theme={null}
Using Minimo: how many contacts do I have, what segments exist, and which email templates are ready to send?
```

From there, Mo's tools cover the full workspace: search and upsert **contacts**, build **segments**, create and send **email / WhatsApp templates and campaigns**, inspect **automations** and their performance, check **connection status** (sender domain, database sync, WhatsApp), and even query Minimo's own **docs** — so the agent can answer "how does Minimo work?" without leaving the chat.

## Troubleshooting

* **401 Unauthorized** — the key is missing the `mcp:invoke` permission, expired, or malformed. Mint a fresh one from the dashboard card.
* **Connector shows no tools** — make sure the URL is exactly `https://api.minimo.it/mcp` (no `/v1` prefix) and the transport is HTTP (not SSE).
* **Wrong workspace** — keys are company-scoped: the agent acts on the company the key was created in. Ask the agent which workspace it's connected to, or reconnect from **Settings → Mo & MCP**.


# AI Prompts
Source: https://docs.minimo.it/guides/introduction

Ready-to-use prompts for AI coding tools to integrate with Minimo

## What are AI Prompts?

These are ready-to-use prompts you can paste directly into AI coding tools like **Lovable**, **V0**, **Replit**, **Cursor**, or **Claude**. Each prompt contains everything the AI agent needs to build a working Minimo integration: API details, authentication, code examples, and edge cases.

Just copy the prompt, paste it into your AI tool, and let it generate the integration code for your application.

## Available Prompts

<CardGroup>
  <Card title="Contact Sync" icon="users" href="/guides/ai-prompts/contact-sync">
    Keep your user database synchronized with Minimo contacts. Covers custom field creation, create-or-update contact
    flows, and lifecycle hooks.
  </Card>
</CardGroup>

## Need a prompt for a specific use case?

Reach out to [info@minimo.it](mailto:info@minimo.it) and we'll create one for you.


# Introduction
Source: https://docs.minimo.it/introduction

Minimo sends email, WhatsApp and SMS triggered by your own database — and Mo, the built-in AI, can run it from your agent.

Minimo is a multichannel messaging platform that runs on **your own database**. Connect
Supabase or Postgres and send email, WhatsApp and SMS triggered by your data — no import,
no sync jobs, no ETL. **Mo**, the built-in AI marketer, reads your database and builds
fields, segments, emails and flows from a plain-language prompt.

You can use Minimo three ways, and these docs are organized around them:

<CardGroup>
  <Card title="Use the product" icon="wand-magic-sparkles" href="/product/introduction">
    How Minimo works — data sync, messaging, automations and integrations. No code required.
  </Card>

  <Card title="Build with the API" icon="code" href="/api-reference/overview/introduction">
    Manage contacts and send email & WhatsApp from your backend with the REST API and TypeScript SDK.
  </Card>

  <Card title="Connect your AI agent" icon="robot" href="/guides/connect-your-agent">
    Drive Minimo from Claude, Cursor or ChatGPT through the Minimo MCP server. Mo's tools, in your agent.
  </Card>
</CardGroup>

## Start here

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/product/quickstart">
    From signup to your first message in a few minutes.
  </Card>

  <Card title="Connect your agent (MCP)" icon="plug" href="/guides/connect-your-agent">
    Point Claude, Cursor or ChatGPT at Minimo and ask it to set things up for you.
  </Card>

  <Card title="Sync your contacts" icon="database" href="/product/data-sync/supabase">
    Connect Supabase or Postgres, or push contacts through the API.
  </Card>

  <Card title="Send your first email" icon="envelope" href="/product/messaging/email">
    Create a template and send a transactional email.
  </Card>
</CardGroup>

## What Minimo does

* **Event-triggered messaging** — send when a row changes, a trial ends, or a payment fails.
* **Database-native** — reads your Supabase or Postgres directly. It does not copy or import your data.
* **WhatsApp without the pain** — one Minimo key, no Meta Business Manager glue, no Twilio, no markup on Meta fees.
* **Mo, the AI marketer** — from a prompt, writes queries, creates dynamic fields, drafts emails, and builds automations, segments and campaigns.
* **Supabase auth emails** — customize signup, magic-link, reset and verify emails without redeploying code.

<Note>
  Prefer to let an AI set Minimo up for you? Point your agent at the [agent-setup instructions](/agent-setup) and it
  will connect the Minimo MCP server itself.
</Note>


# Lifecycle automations
Source: https://docs.minimo.it/product/automations/lifecycle

Send onboarding, trial-conversion and win-back messages triggered by your own database.

An **automation** is a flow that watches your data and messages contacts when something happens —
a row changes, a trial ends, a payment fails, a contact enters a segment. Because Minimo reads your
database directly, the triggers are your real application state, not a copy.

## What you can build

* **Onboarding** — welcome a new signup, then follow up over the next days if they haven't finished setup.
* **Trial conversion** — nudge trial users as the trial-end date approaches; stop when they upgrade.
* **Win-back** — re-engage contacts who went inactive.
* **Operational** — receipts, renewal reminders, payment-failed dunning.

Each step can send **email, WhatsApp or SMS**, wait, branch on a condition, or check a **goal**
(did the contact do the thing you wanted?).

## Build a flow

<Steps>
  <Step title="Choose a trigger">
    In **Automations → New**, pick what starts the flow: a new or changed contact, entering a segment, or a field
    crossing a threshold (e.g. `trial_ends_at` within 3 days).
  </Step>

  <Step title="Add steps">Drag in message steps (pick a template), waits, and conditions in the visual builder.</Step>

  <Step title="Set a goal">
    Define the outcome (e.g. "plan = paid"). Contacts who reach the goal exit the flow, and you can measure conversion
    against it.
  </Step>

  <Step title="Turn it on">Activate the automation. It runs continuously against your live data.</Step>
</Steps>

<Tip>
  Describe the flow in one sentence and let **Mo** build the whole automation — trigger, steps and emails — then review
  it in the builder. See [Build with Mo](/product/mo).
</Tip>

## Measure it

Each automation reports how many contacts entered, where they are, and goal conversion, per node.
Your connected agent can answer questions like *"how is the trial-conversion flow performing?"* —
see [Connect your agent](/guides/connect-your-agent).

<Note>
  Automations rely on the fields Minimo can see. Make sure the data you trigger on (dates, plan, status) is synced — see
  [Data sync](/product/data-sync/supabase).
</Note>


# API Sync
Source: https://docs.minimo.it/product/data-sync/api-sync

Sync contacts with Minimo using the REST API

## Overview

If your application doesn't use PostgreSQL, you can sync contacts with Minimo using our REST API. Every time a user is created or updated in your app, you call the Minimo API to keep contacts in sync.

<Warning>
  **Using PostgreSQL or Supabase?** We recommend the [native Supabase Connection](/product/data-sync/supabase) instead —
  it's plug-and-play, requires no code, and has no API failure points.
</Warning>

***

## How it works

1. **On app startup**: ensure your custom fields exist in Minimo
2. **On user create/update**: call the upsert endpoint to sync the contact
3. **On user delete** (optional): call the delete endpoint to remove the contact

The upsert endpoint handles both creation and updates automatically, matching contacts by email or phone.

***

## Implementation

### Use an AI coding tool

The fastest way to implement API sync is with our ready-made AI prompt. Give it to your AI coding tool (Cursor, Claude, Lovable, V0, Replit) and it will generate the full integration for you.

<Card title="Contact Sync AI Prompt" icon="wand-magic-sparkles" href="/guides/ai-prompts/contact-sync">
  Ready-to-use prompt that generates a complete contact sync integration with custom field setup, upsert logic, and
  lifecycle hooks.
</Card>

### Build it manually

If you prefer to implement it yourself, refer to the API reference:

<CardGroup>
  <Card title="Upsert Contact" icon="user-plus" href="/api-reference/core-data/contacts/upsert">
    Create or update a contact by email or phone.
  </Card>

  <Card title="Custom Fields" icon="list" href="/api-reference/core-data/custom-fields/list">
    List and create custom field definitions.
  </Card>
</CardGroup>


# Supabase Connection
Source: https://docs.minimo.it/product/data-sync/supabase

Sync your contacts automatically with a native, plug-and-play database connection

## Overview

The Supabase Connection is Minimo's native integration for PostgreSQL and Supabase databases. It reads your user data directly from your database in **read-only mode**, keeping your Minimo contacts automatically in sync — with zero code and zero API calls.

<Tip>
  This is the **recommended** way to sync contacts if your application uses PostgreSQL or Supabase. It's simpler, more
  reliable, and requires no maintenance.
</Tip>

***

## Why use the native connection

|                    | Native Connection      | API Sync                       |
| ------------------ | ---------------------- | ------------------------------ |
| **Setup**          | Plug-and-play          | Requires code                  |
| **Maintenance**    | None                   | You maintain the sync logic    |
| **Failure points** | None (direct DB read)  | API calls can fail             |
| **Data location**  | Stays in your database | Sent via HTTP requests         |
| **Real-time**      | Automatic sync         | Depends on your implementation |
| **Code required**  | None                   | Yes                            |

***

## How it works

<Steps>
  <Step title="Connect your database">
    Provide your PostgreSQL or Supabase connection details. Minimo connects in **read-only mode** — it will never write
    to or modify your database.
  </Step>

  <Step title="Map your data">
    Tell Minimo which table contains your users and how fields map to Minimo contacts (email, phone, name, custom
    fields).
  </Step>

  <Step title="Automatic sync">
    Minimo continuously reads your database and keeps contacts in sync. New users are created, updated users are updated
    — automatically.
  </Step>
</Steps>

***

## What gets synced

* **Contact fields**: email, phone, first name, last name
* **Custom fields**: any column in your users table can be mapped to a Minimo custom field
* **Status**: map a column to track active/inactive/churned status

<Info>
  Your data stays entirely in your infrastructure. Minimo reads it in real-time but never stores a copy of your
  database.
</Info>

***

## Requirements

* A **PostgreSQL** database (including Supabase, Neon, Railway, or any PostgreSQL-compatible provider)
* Read-only database credentials for Minimo
* Network access from Minimo's servers to your database (IP allowlisting may be required)

***

## Get started

The Supabase Connection is set up by the Minimo team for your account. Contact us to get started:

<Card title="Set up your connection" icon="envelope" href="mailto:info@minimo.it">
  Email **[info@minimo.it](mailto:info@minimo.it)** and we'll configure the native connection for your database.
</Card>

***

## FAQ

<AccordionGroup>
  <Accordion title="Is my data safe?">
    Minimo connects in **read-only mode**. It cannot modify, delete, or write any data to your database. The connection credentials should be configured with read-only permissions.
  </Accordion>

  <Accordion title="Does it work with any PostgreSQL database?">
    Yes. While we call it the "Supabase Connection", it works with any PostgreSQL-compatible database — Supabase, Neon,
    Railway, AWS RDS, DigitalOcean, self-hosted, etc.
  </Accordion>

  <Accordion title="Can I use both the native connection and API sync?">
    Yes, but it's usually not needed. The native connection handles contact sync automatically. You might still use the
    API for specific actions like sending messages.
  </Accordion>

  <Accordion title="What if I need to sync data from a non-PostgreSQL database?">
    Use the [API Sync](/product/data-sync/api-sync) approach instead. You can also give our [AI Prompt](/guides/ai-prompts/contact-sync) to your coding assistant to implement it quickly.
  </Accordion>
</AccordionGroup>


# ActiveCampaign Integration
Source: https://docs.minimo.it/product/integrations/activecampaign

Use Minimo as the messaging engine inside your ActiveCampaign automations

## What this integration does

### Minimo + ActiveCampaign

Use Minimo as the messaging engine inside your ActiveCampaign automations.

Keep contacts in sync between ActiveCampaign and Minimo, then trigger high-deliverability email and WhatsApp messages from your existing automations.

## Available actions

### Create or Update Contact in Minimo

When a contact enters an ActiveCampaign automation, add or update them in Minimo with the right tags, custom fields, and identifiers. This keeps your product-data-driven CRM in Minimo aligned with your marketing lists.

### Send Email Template with Minimo

From any step in an ActiveCampaign automation, call a Minimo email template. You keep segmentation and logic in ActiveCampaign, while Minimo handles template management and deliverability.

### Send WhatsApp Template with Minimo

Add WhatsApp as a channel in your ActiveCampaign flows. Use Minimo to send pre-approved WhatsApp templates for onboarding, transactional notifications, or re-engagement messages triggered by ActiveCampaign events.

**Planned extensions**: more actions to trigger workflows, track events, and sync campaign performance back to Minimo.


# Zapier Integration
Source: https://docs.minimo.it/product/integrations/zapier

Connect Minimo with thousands of apps using Zapier

## What this integration does

### Minimo + Zapier

Use Zapier to plug Minimo into thousands of apps without writing code.

Every time something happens in your stack – a new lead, a paid order, a changed subscription – you can update your contacts in Minimo and trigger email or WhatsApp messages in just a few clicks.

## Available actions

### Create or Update Contact in Minimo

Keep your Minimo contacts in sync with data from forms, CRMs, payment platforms, and more. If the contact already exists, Minimo updates it; if not, it creates a new one.

### Send Email Template with Minimo

Trigger any Minimo email template directly from a Zap. Use data from previous steps (form fields, order details, CRM properties) to personalize the message.

### Send WhatsApp Template with Minimo

Trigger approved WhatsApp templates via Minimo from any Zap event. Ideal for time-sensitive alerts such as trial expiring, order updates, booking confirmations, or payment reminders.

**Coming soon**: additional actions (events tracking, workflows and goals) to orchestrate more advanced lifecycle automations.


# Product
Source: https://docs.minimo.it/product/introduction

Learn how Minimo works — features, integrations, and setup guides

Minimo is a multichannel messaging platform: manage contacts, send personalized email, WhatsApp and
SMS, and automate your customer lifecycle — all driven by your own database.

New here? Start with the [Quickstart](/product/quickstart).

***

## Messaging

<CardGroup>
  <Card title="Send email" icon="envelope" href="/product/messaging/email">
    Create transactional templates and send them from the app, the API, or Mo.
  </Card>

  <Card title="Send on WhatsApp" icon="whatsapp" href="/product/messaging/whatsapp">
    Connect a number, get a template approved by Meta, and send.
  </Card>
</CardGroup>

## Automations & AI

<CardGroup>
  <Card title="Lifecycle automations" icon="diagram-project" href="/product/automations/lifecycle">
    Onboarding, trial-conversion and win-back flows triggered by your data.
  </Card>

  <Card title="Build with Mo" icon="wand-magic-sparkles" href="/product/mo">
    The built-in AI marketer that builds fields, segments, emails and flows from a prompt.
  </Card>
</CardGroup>

## Data Sync

Keep your contact database in sync with Minimo. Choose the method that fits your stack:

<CardGroup>
  <Card title="Supabase Connection" icon="database" href="/product/data-sync/supabase">
    Native, plug-and-play connection for PostgreSQL and Supabase databases. Zero code required.
  </Card>

  <Card title="API Sync" icon="code" href="/product/data-sync/api-sync">
    Sync contacts via Minimo's REST API. Best for custom backends or non-PostgreSQL databases.
  </Card>
</CardGroup>

## Supabase auth emails

<CardGroup>
  <Card title="Customize auth emails" icon="key" href="/product/supabase-auth-emails">
    Redesign Supabase signup, magic-link, reset and verify emails — without redeploying.
  </Card>
</CardGroup>

***

## Integrations

Connect Minimo with the tools you already use:

<CardGroup>
  <Card title="Zapier" icon="bolt" href="/product/integrations/zapier">
    Connect Minimo to thousands of apps. Sync contacts and trigger messages from any Zap.
  </Card>

  <Card title="ActiveCampaign" icon="envelope" href="/product/integrations/activecampaign">
    Use Minimo as the messaging engine inside your ActiveCampaign automations.
  </Card>
</CardGroup>


# Send email
Source: https://docs.minimo.it/product/messaging/email

Create transactional email templates and send them from the app, the API, or Mo.

Minimo sends two kinds of email:

* **Transactional** — personalized, event-driven messages (welcome, receipt, password reset). Sent to one contact at a time, usually triggered by your app or an automation.
* **Marketing campaigns** — bulk sends to a segment or list.

This page covers the transactional path; campaigns work the same way but target a segment.

## Before you start

<Steps>
  <Step title="Verify a sending domain">
    In **Settings → Domain and tracking**, add your domain and set the DNS records Minimo shows you. Verifying the
    domain (SPF/DKIM) is what keeps your mail out of spam.
  </Step>

  <Step title="Whitelist a sender address">
    Add the `From` address you'll send with (e.g. `hello@yourdomain.com`). It must be on a verified domain.
  </Step>
</Steps>

## Create a template

In **Templates → New**, write the subject, preview text and body. Templates support **dynamic
fields** — `{{firstName}}`, `{{plan}}`, any contact field or custom field — which Minimo fills per
recipient at send time.

<Tip>
  Describe the email in plain language and let **Mo** draft it: subject, body and dynamic fields. See [Build with
  Mo](/product/mo).
</Tip>

## Send it

<Tabs>
  <Tab title="From the app">
    Open the template and use **Send test** to send yourself a copy, or wire it into an
    [automation](/product/automations/lifecycle) so it fires on an event.
  </Tab>

  <Tab title="From the API">
    Send a stored template to a contact with a single call. See [Send an email
    template](/api-reference/messaging-channels/email/send-template) for the full reference, or [Send a one-shot HTML
    email](/api-reference/messaging-channels/email/send-html) to send a pre-rendered payload without a stored template.
  </Tab>

  <Tab title="From your agent">
    Ask your connected agent: *"Send the welcome email to [jane@example.com](mailto:jane@example.com)."* Mo picks the template and sends. See
    [Connect your agent](/guides/connect-your-agent).
  </Tab>
</Tabs>

## Track results

Every send records delivery, open and click events. Check them in the template's stats in the app,
or via the API — see [Email template stats](/api-reference/messaging-channels/email/stats).

<Note>
  Sending the same message repeatedly (e.g. retrying a failed request)? Use an [idempotency
  key](/api-reference/overview/conventions) so a contact isn't emailed twice.
</Note>


# Send on WhatsApp
Source: https://docs.minimo.it/product/messaging/whatsapp

Connect a WhatsApp number, get a template approved by Meta, and send — no Meta Business Manager setup.

Minimo lets you send WhatsApp from your database events without the usual Meta Business Manager and
Twilio glue. One Minimo connection covers the number, the templates and the inbound replies.

## How WhatsApp sending works

WhatsApp business messaging is **template-first**: to start a conversation you send a message built
from a template that Meta has **approved**. The lifecycle is:

<Steps>
  <Step title="Connect a number">
    In **Settings → Connections**, connect a WhatsApp sender. You can connect more than one number (multi-sender /
    multi-WABA). See [List WhatsApp senders](/api-reference/messaging-channels/whatsapp/list-senders).
  </Step>

  <Step title="Create a template">
    Build the template — body text, variables, buttons. Templates have a **category** (Utility, Marketing,
    Authentication) that affects approval and pricing.
  </Step>

  <Step title="Submit for approval">
    Submit the draft to Meta. It moves through `PENDING` → `APPROVED` (or `REJECTED`). Approval usually takes minutes to
    hours.
  </Step>

  <Step title="Send">
    Once `APPROVED`, send the template to a contact, filling its variables per recipient. See [Send a WhatsApp
    template](/api-reference/messaging-channels/whatsapp/send-template).
  </Step>
</Steps>

<Tip>
  Let **Mo** build and submit templates for you, then send an approved one to a segment — ask your connected agent or
  use the in-app assistant. See [Build with Mo](/product/mo).
</Tip>

## Check template status

A template can only be sent when it's `APPROVED`. List your templates and their status in the app,
or via [List WhatsApp templates](/api-reference/messaging-channels/whatsapp/list-templates).

## Receive replies and events

Minimo receives inbound WhatsApp messages, delivery events and template-status updates for you and
surfaces them in the unified inbox. If you want them in your own backend too, see
[Inbound & webhooks](/api-reference/messaging-channels/whatsapp/inbound-webhooks).

## Let an AI assistant reply

WhatsApp on Minimo is two-way. Assign an **AI assistant** to a number and inbound conversations are
handled automatically — it understands voice notes, photos and reactions, answers from your knowledge
base, and can take real actions like booking. See
[AI assistants on WhatsApp](/product/messaging/whatsapp-assistant).

## Multiple & custom numbers

A single Minimo account can run many WhatsApp numbers (multi-sender / multi-WABA). Because Minimo is
a WhatsApp **Business Solution Provider**, you can give each customer, brand or location its own
custom number — and pick which one a message goes out from with the `sender` field. See
[Custom numbers, multiple numbers & agencies](/product/messaging/whatsapp-numbers).

<Warning>
  Sending a template that isn't approved returns a `template_not_approved` error, and an invalid recipient returns
  `invalid_phone_number`. Numbers must be in E.164 format (e.g. `+15551234567`).
</Warning>


# AI assistants on WhatsApp
Source: https://docs.minimo.it/product/messaging/whatsapp-assistant

Assign an AI assistant to a WhatsApp number. It understands voice notes, photos and reactions, answers from your knowledge base, and can take real actions like booking.

WhatsApp on Minimo is **two-way**. Beyond DB-triggered outbound templates, you can assign an **AI
assistant** to a number so inbound conversations are handled automatically — the assistant reads your
knowledge base and connected data, understands what the customer actually sent, and can *do* things,
not just reply.

## Assign an assistant to a number

In the app, bind an assistant to a WhatsApp channel (number). Inbound messages to that number are
answered by the assistant; replies and history stay in the [unified inbox](/product/messaging/whatsapp),
where a human can take over at any time. Each number can have its **own** assistant — so with
[multiple numbers](/product/messaging/whatsapp-numbers) every brand or client gets a separate assistant.

## What the assistant understands

Customers don't only send text. The assistant reasons about the full message:

<CardGroup>
  <Card title="Voice notes" icon="microphone">
    A voice message is transcribed and understood — the assistant replies to what was *said*, without
    asking the customer to type it out.
  </Card>

  <Card title="Photos & images" icon="image">
    Computer vision reads inbound images — a receipt, a screenshot, a product photo — and the reply
    reflects what's in the picture.
  </Card>

  <Card title="Reactions" icon="heart">
    An emoji reaction is treated as a reaction on the message it targets — not misread as a new
    message, and it never triggers a blind auto-reply.
  </Card>

  <Card title="Knowledge base" icon="book">
    Answers are grounded in your business knowledge, so customer-support questions get accurate,
    on-brand replies.
  </Card>
</CardGroup>

## Assistants can take actions

An assistant can be given **Actions** — calls to your own API — so it can complete tasks on the
customer's behalf, with server-side identity, in-chat confirmation and an audit trail around every
call. Typical actions: look up data, create or reschedule a booking, cancel, check availability.

<Note>
  **In production:** BeautyGo runs its salon booking on a Minimo assistant. A client messages the
  WhatsApp number, the assistant finds the salon, checks availability and books the appointment, then
  answers follow-up questions from BeautyGo's knowledge base — end to end, no human in the loop.
</Note>

Actions are defined as an **Integration → Action → binding** and can be imported directly from an
**OpenAPI** spec (one draft action per operation). Identity-looking parameters (like the customer's
phone) are injected server-side to prevent a customer from acting on someone else's behalf.

<Tip>
  Building templates, segments and automations is done by **Mo**, Minimo's in-app AI marketer — see
  [Build with Mo](/product/mo). The WhatsApp *conversational* assistant described here is the one that
  answers and acts on inbound customer messages.
</Tip>

## Receiving in your own backend

If you want inbound messages, delivery events and template-status updates in your own systems too
(in addition to the assistant handling them), see
[Inbound & webhooks](/api-reference/messaging-channels/whatsapp/inbound-webhooks).


# Custom numbers, multiple numbers & agencies
Source: https://docs.minimo.it/product/messaging/whatsapp-numbers

Minimo is a WhatsApp Business Solution Provider (BSP). Run many numbers under one account and give each of your customers, brands or locations its own custom WhatsApp number.

Minimo is a **WhatsApp Business Solution Provider (BSP)** — we hold the 360dialog partner plan,
handle Meta onboarding and the BSP contract, and pass Meta's conversation fees through at cost.
That means you are not limited to a single WhatsApp number: you can run **many numbers under one
Minimo account**, each with its own display name and templates.

This is the model that lets a platform or agency **give every client, brand or location its own
custom WhatsApp number** — something few providers make easy.

## Who this is for

<CardGroup>
  <Card title="Platforms & marketplaces" icon="layer-group">
    Your end-customers each want to message *their* users from *their own* branded number. Provision
    one per customer instead of sharing a single line.
  </Card>

  <Card title="Agencies & resellers" icon="handshake">
    Manage WhatsApp for a portfolio of brands from one place, and resell WhatsApp messaging without
    running your own BSP contract with Meta.
  </Card>

  <Card title="Multi-location businesses" icon="store">
    A dedicated number per shop, clinic or salon — replies and history stay separated per location.
  </Card>

  <Card title="Support + marketing split" icon="inbox">
    Keep a support line and a marketing line on different numbers (and, if you want, different WABAs).
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="We provision the numbers">
    Minimo runs on a 360dialog **partner** plan that covers **unlimited numbers**. Adding another
    number does not add a per-number platform fee — you only pay Meta's usual conversation fees,
    billed to you at cost.
  </Step>

  <Step title="Connect each number">
    Each WhatsApp number is connected as a **sender** on a company, from **Settings → Connections**
    (or the **Channels** section). A single company can hold more than one number, across one or
    more WhatsApp Business Accounts (multi-sender / multi-WABA).
  </Step>

  <Step title="Pick the sender on every send">
    When you send, you choose which number the message goes out from with the `sender` field. Omit
    it and Minimo uses the company's **preferred** (default) number. See
    [List WhatsApp senders](/api-reference/messaging-channels/whatsapp/list-senders) and
    [Send a WhatsApp template](/api-reference/messaging-channels/whatsapp/send-template).
  </Step>
</Steps>

## Discover the numbers you can send from

The set of numbers a company may send from — with their display name and Meta `phone_number_id` —
is available from the API. This is the value you pass as `sender`:

```bash theme={null}
curl https://api.minimo.it/public/v1/templates/whatsapp/senders \
  -H "Authorization: Bearer mn-abc123-xyz789"
```

Each item exposes the `phoneNumber`, the WhatsApp Business display name (`phoneName`), the Meta
`phoneNumberId`, and whether it is the company default (`isPreferred`). The response is redacted —
it never returns API keys, client IDs or webhook URLs. Full reference:
[List WhatsApp senders](/api-reference/messaging-channels/whatsapp/list-senders).

## Send from a specific number

```bash theme={null}
curl https://api.minimo.it/public/v1/templates/whatsapp/send \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "recipient": "393471234567",
    "type": "template",
    "sender": "+393517654321",
    "template": {
      "name": "appointment_confirmation",
      "components": [
        { "type": "BODY", "parameters": [ { "type": "text", "text": "Jane" } ] }
      ]
    }
  }'
```

<Tip>
  Pair a per-client number with a per-client [AI assistant](/product/messaging/whatsapp-assistant): each
  number can have its own assistant, knowledge base and actions, so every brand gets a fully separate
  WhatsApp presence.
</Tip>

<Warning>
  Passing a `sender` that isn't one of the company's connected numbers returns
  `WHATSAPP_SENDER_NOT_FOUND`. Always source the value from
  [List WhatsApp senders](/api-reference/messaging-channels/whatsapp/list-senders).
</Warning>

## Adding numbers at scale

Provisioning many numbers (per-customer onboarding, agency portfolios, white-label resale) is set up
with us directly — reach out at [info@minimo.it](mailto:info@minimo.it) and we'll wire up the numbers
and WABAs for your account. Once connected, they appear in
[List WhatsApp senders](/api-reference/messaging-channels/whatsapp/list-senders) and are usable
immediately via the `sender` field.


# Build with Mo
Source: https://docs.minimo.it/product/mo

Mo is Minimo's built-in AI marketer — it reads your database and builds fields, segments, emails, campaigns and automations from a prompt.

**Mo** is the AI marketer built into Minimo. It can read your connected database and your workspace,
and turn a plain-language request into real work: dynamic fields, segments, email and WhatsApp
templates, campaigns and automations.

## What Mo can do

* **Understand your data** — inspect your connected schema and propose column → field mappings.
* **Create dynamic fields** — derive the fields you need for personalization and targeting.
* **Build segments** — turn "trial users in the US who haven't logged in for 7 days" into a filtered list.
* **Draft messages** — write email and WhatsApp templates, subjects, preview text and buttons.
* **Build automations & campaigns** — generate a full lifecycle flow or a one-off campaign from a description.
* **Report** — answer "how is this automation performing?" or "how many contacts do I have?".

## Two ways to use Mo

<CardGroup>
  <Card title="In the app" icon="wand-magic-sparkles" href="https://app.minimo.it">
    Use **Ask Mo** inside Minimo to create and edit blocks, automations and campaigns.
  </Card>

  <Card title="From your AI agent" icon="robot" href="/guides/connect-your-agent">
    Connect Minimo to Claude, Cursor or ChatGPT via MCP and drive Mo's tools from your own agent.
  </Card>
</CardGroup>

## Mo everywhere

Beyond the app, Mo is reachable from the tools you already work in — Claude, Cursor and other MCP
clients, plus Slack and Telegram — from **Settings → Mo & MCP**. The MCP connection exposes Mo's
full tool set (contacts, segments, templates, campaigns, automations, connection status, and Minimo's
own docs) to your agent.

<Tip>
  Start with a read-only prompt to see what Mo can see: *"Using Minimo, summarize my contacts, segments and email
  templates."*
</Tip>

## Good prompts

* "Create a custom field `lifecycle_stage` and set it from my `subscriptions` table."
* "Build a segment of users whose trial ends in the next 3 days and who are still on the free plan."
* "Write a friendly win-back email for contacts inactive for 30 days, using their first name."
* "Create an onboarding automation: welcome email now, a tips email after 2 days, stop when they upgrade."

For ready-to-paste prompts aimed at AI coding tools, see [AI Prompts](/guides/introduction).


# Quickstart
Source: https://docs.minimo.it/product/quickstart

From signup to your first message in a few minutes.

This guide takes you from a new account to your first sent message. Pick the path that fits you:
the **no-code product**, the **API**, or **your AI agent**.

<Steps>
  <Step title="Create your workspace">
    Sign up at [app.minimo.it](https://app.minimo.it) and create (or pick) a workspace. Everything in
    Minimo is scoped to a workspace (your company).
  </Step>

  <Step title="Bring in your contacts">
    Connect your data so Minimo can message the right people:

    <CardGroup>
      <Card title="Supabase / Postgres" icon="database" href="/product/data-sync/supabase">
        Native, read-only connection. Minimo reads your database directly — no import.
      </Card>

      <Card title="API sync" icon="code" href="/product/data-sync/api-sync">
        Push contacts from your backend with a single upsert call.
      </Card>
    </CardGroup>

    Just testing? Add one contact by hand from **Contacts → New**, or upsert one via the API.
  </Step>

  <Step title="Set up a channel">
    * **Email** — add and verify a sending domain, then whitelist a sender address
      (**Settings → Domain and tracking**).
    * **WhatsApp** — connect a number once (**Settings → Connections**); no Meta Business Manager
      setup required. See [Send on WhatsApp](/product/messaging/whatsapp).
  </Step>

  <Step title="Send your first message">
    Create a template and send it:

    <CardGroup>
      <Card title="Send an email" icon="envelope" href="/product/messaging/email">
        Create a transactional template and send it to a contact.
      </Card>

      <Card title="Send on WhatsApp" icon="whatsapp" href="/product/messaging/whatsapp">
        Submit a template for Meta approval, then send it.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Prefer to build with the API?

Create an API key in **Developer → API keys**, then call the REST API. Start with
[Authentication](/api-reference/overview/introduction) and
[Create or update a contact](/api-reference/core-data/contacts/upsert), then
[Send an email template](/api-reference/messaging-channels/email/send-template).

```bash theme={null}
curl https://api.minimo.it/public/v1/contacts \
  -H "Authorization: Bearer mn-YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "firstName": "Jane" }'
```

## Prefer to let an AI do it?

Connect Minimo to Claude, Cursor or ChatGPT and ask it in plain language — it can create fields,
segments, templates and automations for you.

<Card title="Connect your agent (MCP)" icon="robot" href="/guides/connect-your-agent">
  Point your agent at Minimo and let Mo's tools do the setup.
</Card>


# Supabase auth emails
Source: https://docs.minimo.it/product/supabase-auth-emails

Customize Supabase signup, magic-link, reset and verify emails — without redeploying code.

If your app uses **Supabase Auth**, the default authentication emails (confirm signup, magic link,
reset password, verify email) are plain and hard to change — editing them usually means touching
project config. Minimo lets you design them like any other template and takes over sending, so you
can change copy and branding **without redeploying**.

## What you can customize

* **Confirm signup**
* **Magic link**
* **Reset password**
* **Change email / verify**

Each becomes a Minimo template with your branding and dynamic fields, including the auth variables
Supabase provides (such as the confirmation link/token).

## Set it up

<Steps>
  <Step title="Connect Supabase">
    Connect your Supabase project to Minimo — see [Supabase connection](/product/data-sync/supabase).
  </Step>

  <Step title="Point auth emails at Minimo">
    In your Minimo workspace, enable auth-email handling and follow the steps to route Supabase Auth emails through
    Minimo.
  </Step>

  <Step title="Design each template">
    Edit the signup, magic-link, reset and verify templates in **Templates**. Keep the auth link/token variable in place
    so the flow still works.
  </Step>
</Steps>

<Warning>
  Auth emails are on the critical path for signing in. Always send yourself a **test** of each template and click the
  link end-to-end before going live — a broken magic-link variable locks users out.
</Warning>

<Tip>Ask **Mo** to redesign an auth email to match your brand, then test it. See [Build with Mo](/product/mo).</Tip>