# Mailchimp Integration via LowCodeAPI

## Overview

Mailchimp (Transactional API via Mandrill) is an email marketing platform for sending newsletters, transactional emails, and managing email campaigns.

## Base Endpoint

```
https://api.lowcodeapi.com/mailchimp/
```

## Authentication

LowCodeAPI handles authentication automatically. You only need to:

1. **Sign up** at https://mailchimp.com/
2. **Connect your account** in LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Mailchimp API key from database
- Apply it to each request

**Auth Type**: `API Key` (Body-based authentication)

## API Categories

- Marketing Email
- Messages

## Common Endpoints

### Category: Messages

#### Send new message

**Method**: `POST` | **LowCodeAPI Path**: `/api/1.0/messages/send`

**Full URL**:
```
https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send?api_token={api_token}
```

**Description**: Send a new transactional message through the Transactional API.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | object | Yes | Message object with details |
| `key` | string | Yes | Your API key (auto-included) |
| `async` | boolean | No | Enable background sending mode for bulk |
| `ip_pool` | string | No | Name of dedicated IP pool |
| `send_at` | string | No | UTC timestamp to schedule sending |

**Message Object Fields**:

- `subject`: Email subject line
- `text`: Plain text body
- `html`: HTML body
- `from_email`: Sender email address
- `from_name`: Sender name
- `to`: Array of recipient objects
- `cc`: Array of CC recipients
- `bcc`: Array of BCC recipients

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "message": {
      "subject": "Welcome to Our Service",
      "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
      "text": "Welcome! Thanks for signing up.",
      "from_email": "[email protected]",
      "from_name": "Example Team",
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe",
          "type": "to"
        }
      ]
    }
  }'
```

**Official Documentation**: https://mailchimp.com/developer/transactional/api/messages/send-new-message/

---

#### Send using message template

**Method**: `POST` | **LowCodeAPI Path**: `/api/1.0/messages/send-template`

**Full URL**:
```
https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send-template?api_token={api_token}
```

**Description**: Send a transactional message using a stored template.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_name` | string | Yes | Immutable name/slug of template |
| `template_content` | object | Yes | Array of template content to send |
| `message` | object | Yes | Message info (without html content) |
| `key` | string | Yes | Your API key (auto-included) |
| `async` | boolean | No | Enable background sending mode |
| `ip_pool` | string | No | Dedicated IP pool name |
| `send_at` | string | No | UTC timestamp for scheduled sending |

**Example Request**:
```bash
# Send email using a pre-configured template
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send-template?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "template_name": "welcome-email",
    "template_content": [
      {
        "name": "headline",
        "content": "Welcome to Our Platform!"
      }
    ],
    "message": {
      "subject": "Welcome!",
      "from_email": "[email protected]",
      "to": [
        {
          "email": "[email protected]",
          "type": "to"
        }
      ]
    }
  }'
```

**Official Documentation**: https://mailchimp.com/developer/transactional/api/messages/send-using-message-template/

---

#### Search messages by date

**Method**: `POST` | **LowCodeAPI Path**: `/api/1.0/messages/search`

**Full URL**:
```
https://api.lowcodeapi.com/mailchimp/api/1.0/messages/search?api_token={api_token}
```

**Description**: Search for sent messages by date range and other filters.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Your API key (auto-included) |
| `query` | string | No | Search terms to find matching messages |
| `date_from` | string | No | Start date for search |
| `date_to` | string | No | End date for search |
| `tags` | array | No | Filter by message tags |
| `limit` | number | No | Limit number of results |
| `senders` | array | No | Filter by sender email addresses |

**Example Request**:
```bash
# Search for messages sent in a date range
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/search?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "limit": 100
  }'
```

**Official Documentation**: https://mailchimp.com/developer/transactional/api/messages/search-messages-by-date/

---

## Usage Examples

### Example 1: Send Welcome Email

Send a personalized welcome message to new users.

```bash
# Send simple text and HTML email
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "message": {
      "subject": "Welcome to Our Platform!",
      "html": "<h1>Welcome Aboard!</h1><p>Thank you for joining us. We are excited to have you.</p>",
      "text": "Welcome Aboard! Thank you for joining us.",
      "from_email": "[email protected]",
      "from_name": "The Team",
      "to": [
        {
          "email": "[email protected]",
          "name": "Jane Smith",
          "type": "to"
        }
      ]
    }
  }'
```

### Example 2: Send Using Template

Use pre-built templates for consistent branding.

```bash
# Send email using stored template
# template_name must exist in your Mailchimp account
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send-template?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "template_name": "order-confirmation",
    "template_content": [
      {"name": "order_number", "content": "12345"},
      {"name": "customer_name", "content": "John Doe"}
    ],
    "message": {
      "to": [
        {
          "email": "[email protected]",
          "type": "to"
        }
      ]
    }
  }'
```

### Example 3: Bulk Email Sending

Send to multiple recipients efficiently.

```bash
# Send to multiple recipients at once
# Enable async mode for better performance with bulk
curl -X POST "https://api.lowcodeapi.com/mailchimp/api/1.0/messages/send?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_MAILCHIMP_API_KEY",
    "async": true,
    "message": {
      "subject": "Monthly Newsletter",
      "html": "<p>Your monthly update is here...</p>",
      "from_email": "[email protected]",
      "to": [
        {"email": "[email protected]", "type": "to"},
        {"email": "[email protected]", "type": "to"},
        {"email": "[email protected]", "type": "to"}
      ]
    }
  }'
```

## Complete Endpoint Reference

For a complete list of all endpoints and their parameters, refer to:
- **OpenAPI Definition**: `https://backend.lowcodeapi.com/mailchimp/definition`
- **Official Provider Documentation**: https://mailchimp.com/developer/transactional/api/

## Rate Limits & Best Practices

- Use async mode for bulk sending to improve performance
- Template-based emails ensure consistent branding
- Search messages to monitor delivery and engagement
- Validate recipient emails before sending

## Error Handling

Standard HTTP status codes apply. Common errors include invalid API keys, malformed message objects, or rate limiting issues.