email-serverr-cli/README.md

# email-serverr-cli

Go client library for the Email Server API.

## Install

```bash
go get gitea.s1f.ren/shiran/email-serverr-cli
```

## Quick Start

### Management Client (ServiceAuth)

```go
package main

import (
    "context"
    "fmt"
    emailcli "gitea.s1f.ren/shiran/email-serverr-cli"
)

func main() {
    client := emailcli.NewServiceClient(
        "https://your-server.com",
        "your-service-token",
    )

    // List accounts
    accounts, err := client.ListAccounts(context.Background(), emailcli.AccountListQuery{
        PaginationQuery: emailcli.PaginationQuery{Page: 1, PageSize: 20},
    })
    if err != nil {
        panic(err)
    }
    for _, a := range accounts.List {
        fmt.Printf("Account: %s (ID: %d)\n", a.Name, a.ID)
    }
}
```

### Mail Sending Client (AppAuth)

```go
client := emailcli.NewAppClient(
    "https://your-server.com",
    "your-app-key",
    "your-app-secret",
)

resp, err := client.SendMail(context.Background(), emailcli.SendMailReq{
    To:      []string{"recipient@example.com"},
    Subject: "Hello",
    Body:    "<h1>Hello World</h1>",
    Channel: "default",
})
if err != nil {
    panic(err)
}
fmt.Printf("Mail sent: log_id=%d status=%s\n", resp.MailLogID, resp.Status)
```

## Authentication

| Mode | Constructor | Header | Use Case |
|------|-------------|--------|----------|
| ServiceAuth | `NewServiceClient` | `Authorization: Bearer <token>` | Management APIs |
| AppAuth | `NewAppClient` | `X-App-Key` + `X-App-Secret` | Mail sending |

## API Reference

### Mail (AppAuth)

| Method | Description |
|--------|-------------|
| `SendMail` | Send an email |

### Accounts (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateAccount` | Create mail account |
| `ListAccounts` | List accounts with filters |
| `GetAccount` | Get account details |
| `UpdateAccount` | Update account |
| `DeleteAccount` | Delete account |
| `ResetAccountSecret` | Reset app secret |

### Signatures (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateSignature` | Create signature |
| `ListSignatures` | List signatures with filters |
| `GetSignature` | Get signature details |
| `UpdateSignature` | Update signature |
| `DeleteSignature` | Delete signature |
| `AuditSignature` | Approve or reject signature |

### Mail Logs (ServiceAuth)

| Method | Description |
|--------|-------------|
| `ListMailLogs` | List mail logs with filters |
| `GetMailLog` | Get mail log detail with body |
| `GetMailStats` | Get status statistics |

### Quotas (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateQuota` | Create quota |
| `ListQuotas` | List quotas with filters |
| `GetQuotaSummary` | Get quota summary for account |
| `UpdateQuota` | Update quota |
| `DeleteQuota` | Delete quota |

### Channels (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateChannel` | Create channel |
| `ListChannels` | List channels with filters |
| `UpdateChannel` | Update channel |
| `DeleteChannel` | Delete channel |

### Sender Accounts (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateSender` | Create sender under channel |
| `ListSendersByChannel` | List senders for channel |
| `UpdateSender` | Update sender |
| `DeleteSender` | Delete sender |

### Audits (ServiceAuth)

| Method | Description |
|--------|-------------|
| `ListAuditPending` | List pending audit items |
| `GetAuditPendingDetail` | Get pending item detail |
| `ApproveAudit` | Approve single item |
| `RejectAudit` | Reject single item |
| `BatchApproveAudit` | Batch approve |
| `BatchRejectAudit` | Batch reject |
| `ListAuditLogs` | List audit history |
| `GetAuditStats` | Get audit statistics |

### Audit Rules (ServiceAuth)

| Method | Description |
|--------|-------------|
| `CreateAuditRule` | Create rule |
| `ListAuditRules` | List all rules |
| `GetAuditRule` | Get rule details |
| `UpdateAuditRule` | Update rule |
| `DeleteAuditRule` | Delete rule |
| `UpdateAuditRuleStatus` | Toggle rule status |
| `TestAuditRule` | Test rules against sample |

### Queue (ServiceAuth)

| Method | Description |
|--------|-------------|
| `GetQueueStatus` | Get queue lengths |
| `ListQueuePending` | List pending queue items |
| `CancelQueueItem` | Cancel queued mail |
| `RetryQueueItem` | Retry failed mail |

### Health Checks (ServiceAuth)

| Method | Description |
|--------|-------------|
| `ListCheckLogs` | List check logs |
| `GetCheckSummary` | Get sender health summary |
| `TriggerCheck` | Trigger health check |

## Error Handling

```go
resp, err := client.SendMail(ctx, req)
if err != nil {
    var apiErr *emailcli.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error: code=%d message=%s\n", apiErr.Code, apiErr.Message)
    }
}
```

## Options

```go
client := emailcli.NewServiceClient(
    "https://your-server.com",
    "token",
    emailcli.WithTimeout(60 * time.Second),
    emailcli.WithHTTPClient(customClient),
)
```