All-Resources/[phone]/codem-phone/docs/apps/mail.md

# Mail API Documentation

This document describes the available exports for sending mail programmatically from other resources.

## Exports

### SendMailToPlayer

Send mail to a player using their server source ID.

```lua
exports['codem-phone']:SendMailToPlayer(source, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Player's server source ID |
| data | table | Yes | Mail data (see below) |

**Example:**
```lua
local result = exports['codem-phone']:SendMailToPlayer(source, {
    title = "Welcome!",
    description = "Welcome to our server!",
    sender_name = "Server",
    sender_email = "admin@server"
})
```

---

### SendMailToIdentifier

Send mail to a player using their identifier (citizenid, license, etc.).

```lua
exports['codem-phone']:SendMailToIdentifier(identifier, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| identifier | string | Yes | Player's identifier |
| data | table | Yes | Mail data (see below) |

**Example:**
```lua
local result = exports['codem-phone']:SendMailToIdentifier("ABC12345", {
    title = "Package Delivered",
    description = "Your package has been delivered!",
    sender_name = "PostOP",
    sender_email = "delivery@postop"
})
```

---

### SendMailToPhone

Send mail to a player using their phone number.

```lua
exports['codem-phone']:SendMailToPhone(phoneNumber, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| phoneNumber | string | Yes | Player's phone number |
| data | table | Yes | Mail data (see below) |

**Example:**
```lua
local result = exports['codem-phone']:SendMailToPhone("555-1234", {
    title = "Appointment Reminder",
    description = "Your appointment is tomorrow at 10:00 AM",
    sender_name = "Hospital",
    sender_email = "info@hospital"
})
```

---

### SendMailToEmail

Send mail to a player using their email address.

```lua
exports['codem-phone']:SendMailToEmail(email, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| email | string | Yes | Player's email address |
| data | table | Yes | Mail data (see below) |

**Example:**
```lua
local result = exports['codem-phone']:SendMailToEmail("john@codem", {
    title = "Account Update",
    description = "Your account settings have been updated.",
    sender_name = "Bank",
    sender_email = "support@bank"
})
```

---

### SendMailToMultiplePlayers

Send mail to multiple players at once using their identifiers.

```lua
exports['codem-phone']:SendMailToMultiplePlayers(identifiers, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| identifiers | table | Yes | List of player identifiers (max 50) |
| data | table | Yes | Mail data (see below) |

**Example:**
```lua
local result = exports['codem-phone']:SendMailToMultiplePlayers({
    "ABC12345",
    "DEF67890",
    "GHI11111"
}, {
    title = "Server Announcement",
    description = "Server maintenance scheduled for tonight.",
    sender_name = "Admin",
    sender_email = "admin@server"
})

print("Sent: " .. result.sentCount .. ", Failed: " .. result.failedCount)
```

---

## Mail Data Structure

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | Yes | Mail subject (max 200 characters) |
| description | string | Yes | Mail content (max 5000 characters) |
| sender_name | string | No | Sender's display name (default: "System") |
| sender_email | string | No | Sender's email address (default: "system@codem") |
| sender_icon | string | No | URL to sender's icon image |
| sender_identifier | string | No | Sender's identifier (default: "system") |
| attachements | table | No | List of attachments (see below) |
| can_reply | boolean | No | Allow recipient to reply (default: true) |

---

## Attachments

Attachments can include coordinates, items, or custom data.

```lua
attachements = {
    {
        type = "location",
        label = "Meeting Point",
        coords = { x = 100.0, y = 200.0, z = 30.0 }
    },
    {
        type = "item",
        label = "Reward",
        item = "bread",
        amount = 5
    }
}
```

---

## Return Value

All exports return a table with the following structure:

```lua
{
    success = true/false,
    message = "mail.success.mailSent" or "mail.errors.xxx",
    mail = { ... }  -- Mail object if successful
}
```

For `SendMailToMultiplePlayers`:

```lua
{
    success = true/false,
    message = "...",
    sentCount = 3,
    failedCount = 1,
    results = {
        { identifier = "ABC12345", success = true, message = "..." },
        { identifier = "DEF67890", success = false, message = "..." }
    }
}
```

---

## Error Messages

| Message | Description |
|---------|-------------|
| mail.errors.invalidSource | Invalid server source ID |
| mail.errors.invalidIdentifier | Invalid player identifier |
| mail.errors.invalidPhoneNumber | Invalid phone number format |
| mail.errors.invalidEmailFormat | Invalid email format |
| mail.errors.invalidData | Invalid mail data table |
| mail.errors.missingRequiredFields | Missing title or description |
| mail.errors.invalidTitle | Title too long or contains invalid characters |
| mail.errors.invalidContent | Description too long or contains invalid characters |
| mail.errors.recipientEmailNotFound | Recipient's email not found |
| mail.errors.phoneNumberNotFound | Phone number not found |
| mail.errors.emailNotFound | Email address not found |
| mail.errors.tooManyRecipients | More than 50 recipients |
| mail.errors.mailNotSent | Database error while sending |