# Mailgun Integration via LowCodeAPI

## Overview

Mailgun is a powerful email API service for sending, receiving, and tracking emails with advanced analytics and validation capabilities.

## Base Endpoint

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

## Authentication

LowCodeAPI handles authentication automatically. You only need to:

1. **Sign up** at https://www.mailgun.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 Mailgun API key from database
- Apply it to each request with proper Basic Auth header

**Auth Type**: `API Key` (Basic Authentication)

## API Categories

- Transactional Email
- Validation
- Accounts and Users
- Logs
- Domains
- Events
- Routes
- Messages
- Stats

## Common Endpoints

### Category: Messages

#### Send Email (Simple)

**Method**: `POST` | **LowCodeAPI Path**: `/v3/domain/messages`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domain/messages?domain={domain}&api_token={api_token}
```

**Description**: Send an email with simple parameters.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Verified domain in Mailgun account |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `from` | string | Yes | Sender email address (must be from verified domain) |
| `to` | string/array | Yes | Recipient email addresses |
| `cc` | string/array | No | CC recipients |
| `bcc` | string/array | No | BCC recipients |
| `subject` | string | Yes | Email subject line |
| `text` | string | No | Plain text body |
| `html` | string | No | HTML body |
| `template` | string | No | Template name |
| `h:X-Header-Name` | string | No | Custom headers |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/mailgun/v3/domain/messages?domain=example.com&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "subject=Hello from Mailgun" \
  -d "text=This is a test email from Mailgun via LowCodeAPI."
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-reference.html#api-reference-endpoint-send

---

#### Send Email (MIME)

**Method**: `POST` | **LowCodeAPI Path**: `/v3/domain/messages.mime`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domain/messages.mime?domain={domain}&api_token={api_token}
```

**Description**: Send a pre-built MIME message.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Verified domain in Mailgun account |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `to` | string | Yes | Recipient email address |

**Request Body**: Raw MIME message content

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/mailgun/v3/domain/messages.mime?domain=example.com&[email protected]&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @message.mime
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-reference.html#api-reference-endpoint-send-mime

---

### Category: Validation

#### Validate Email Address

**Method**: `GET` | **LowCodeAPI Path**: `/v4/address/validate`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v4/address/validate?address={address}&api_token={api_token}
```

**Description**: Validate an email address and check deliverability.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | Yes | Email address to validate |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/mailgun/v4/address/[email protected]&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "address": "[email protected]",
  "is_valid": true,
  "is_deliverable": true,
  "reason": "accepting mail"
}
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-email-validation.html#email-validation

---

#### Validate Email Addresses (Batch)

**Method**: `POST` | **LowCodeAPI Path**: `/v4/address/validate/batch`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v4/address/validate/batch?api_token={api_token}
```

**Description**: Validate multiple email addresses in a single request.

**Query Parameters**:

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

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `addresses` | array | Yes | Array of email addresses to validate |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/mailgun/v4/address/validate/batch?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["[email protected]", "[email protected]", "[email protected]"]
  }'
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-email-validation.html#email-validation

---

### Category: Domains

#### List Domains

**Method**: `GET` | **LowCodeAPI Path**: `/v3/domains`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domains?api_token={api_token}
```

**Description**: Retrieve a list of all domains in your account.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `limit` | number | No | Number of results to return |
| `skip` | number | No | Number of results to skip |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domains?limit=50&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-domains.html#api-reference-endpoint-domains

---

#### Get Domain

**Method**: `GET` | **LowCodeAPI Path**: `/v3/domains/domain`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domains/domain?domain={domain}&api_token={api_token}
```

**Description**: Get information about a specific domain.

**Query Parameters**:

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

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domains/domain?domain=example.com&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-domains.html#api-reference-endpoint-domain

---

### Category: Events

#### Get Events

**Method**: `GET` | **LowCodeAPI Path**: `/v3/domain/events`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domain/events?domain={domain}&api_token={api_token}
```

**Description**: Retrieve event logs for a domain.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Domain name |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `event` | string | No | Filter by event type |
| `limit` | number | No | Maximum records to return (max 300) |
| `begin` | string | No | Timestamp to begin (RFC 2822 or Unix timestamp) |
| `end` | string | No | Timestamp to end (RFC 2822 or Unix timestamp) |

**Example Request**:
```bash
# Get recent delivery events
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/events?domain=example.com&event=delivered&limit=100&api_token=YOUR_API_TOKEN"

# Get all events for a time range
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/events?domain=example.com&begin=2024-01-01T00:00:00Z&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-events.html#api-reference-endpoint-events

---

### Category: Stats

#### Get Total Stats

**Method**: `GET` | **LowCodeAPI Path**: `/v3/domain/stats/total`

**Full URL**:
```
https://api.lowcodeapi.com/mailgun/v3/domain/stats/total?domain={domain}&api_token={api_token}
```

**Description**: Get aggregate statistics for a domain.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Domain name |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `event` | string | No | Filter by event type (can be multiple) |
| `start` | string | No | Start date (default: -30 days) |
| `end` | string | No | End date (default: now) |
| `duration` | string | No | Duration instead of date range |

**Example Request**:
```bash
# Get stats for last 7 days
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/stats/total?domain=example.com&duration=7d&api_token=YOUR_API_TOKEN"

# Get specific event stats
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/stats/total?domain=example.com&event=delivered&event=opened&event=clicked&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://documentation.mailgun.com/en/latest/api-stats.html#api-reference-endpoint-stats-total

---

## Usage Examples

### Example 1: Send Transactional Email

Send a simple text or HTML email.

```bash
# Send plain text email
curl -X POST "https://api.lowcodeapi.com/mailgun/v3/domain/messages?domain=example.com&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "subject=Welcome to Our Service" \
  -d "text=Welcome! Your account has been created successfully."

# Send HTML email with formatting
curl -X POST "https://api.lowcodeapi.com/mailgun/v3/domain/messages?domain=example.com&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "subject=Your Order Has Shipped" \
  -d "html=<h1>Order Shipped</h1><p>Your order #12345 is on its way!</p>"
```

### Example 2: Validate Email Addresses

Check email validity before sending.

```bash
# Validate single email
curl -X GET "https://api.lowcodeapi.com/mailgun/v4/address/[email protected]&api_token=YOUR_API_TOKEN"

# Validate multiple emails at once
curl -X POST "https://api.lowcodeapi.com/mailgun/v4/address/validate/batch?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'
```

### Example 3: Monitor Email Performance

Track delivery rates and engagement.

```bash
# Get recent events
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/events?domain=example.com&event=delivered&limit=50&api_token=YOUR_API_TOKEN"

# Get aggregate statistics
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/stats/total?domain=example.com&duration=30d&api_token=YOUR_API_TOKEN"

# Get stats for specific metrics
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domain/stats/total?domain=example.com&event=sent&event=delivered&event=opened&event=clicked&api_token=YOUR_API_TOKEN"
```

### Example 4: Manage Domains

Configure your email infrastructure.

```bash
# List all domains in account
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domains?api_token=YOUR_API_TOKEN"

# Get specific domain details
curl -X GET "https://api.lowcodeapi.com/mailgun/v3/domains/domain?domain=example.com&api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

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

## Rate Limits & Best Practices

- Always validate email addresses before bulk sending
- Monitor event logs to track delivery issues
- Use dedicated IPs for high-volume sending
- Set up proper DNS records (SPF, DKIM, DMARC) for better deliverability

## Error Handling

Standard HTTP status codes apply. Common issues include unverified domains, invalid recipient addresses, or rate limiting.