> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mellob.in/llms.txt
> Use this file to discover all available pages before exploring further.

# mails package

> Send your first email with Karma Mail in under 2 minutes.

## Install

```bash theme={null}
go get github.com/MelloB1989/karma/mails
go get github.com/MelloB1989/karma/models
```

## Quick start (AWS SES)

```go theme={null}
package main

import (
  "log"

  "github.com/MelloB1989/karma/mails"
  "github.com/MelloB1989/karma/models"
)

func main() {
  // From address must be verified in AWS SES (or domain verified)
  mailer := mails.NewKarmaMail("no-reply@yourdomain.com", mails.AWS_SES)

  // Fill fields as defined in models.SingleEmailRequest
  email := models.SingleEmailRequest{
    // Example fields (check your models package for exact names):
    // To: "dev@acme.com",
    // Subject: "Welcome to Acme",
    // HTML: "<h1>Hello</h1><p>Thanks for joining.</p>",
    // Text: "Hello\nThanks for joining.",
  }

  if err := mailer.SendSingleMail(email); err != nil {
    log.Fatal(err)
  }
}
```

> Currently, `AWS_SES` is supported. `MAILGUN` and `SENDGRID` return an error: “not supported yet”.

## Required environment variables

Set these in your environment (or `.env`) before running:

```bash theme={null}
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxxxxxxx
AWS_REGION=ap-south-1    # use your AWS region, e.g., us-east-1, eu-west-1, ap-south-1
AWS_SES_REGION=ap-south-1  # This overrides AWS_REGION for SES
```

> Ensure your IAM user/role has SES permissions (e.g. `ses:SendEmail`, `ses:SendRawEmail`) in the region you use.

## Verify identities in SES

1. **Verify the sender** address or verify your **domain** in SES.
2. If your account is in the **SES sandbox**, you must also verify recipient emails (or request production access).
3. Confirm you’re using the same **region** for credentials and SES.

Helpful checks:

* From address (e.g., `no-reply@yourdomain.com`) must be **verified**.
* Region in env must match the SES region you configured.

## Create a client

```go theme={null}
mailer := mails.NewKarmaMail("no-reply@yourdomain.com", mails.AWS_SES)
```

## Build an email

`SendSingleMail` expects a `models.SingleEmailRequest`. Use the exact fields from your `models` package. Common fields typically include **To**, **Subject**, **HTML** and/or **Text**.

```go theme={null}
email := models.SingleEmailRequest{
  // Example – adjust to your struct
  // To:      "user@example.com",
  // Subject: "Your OTP",
  // HTML:    "<p>Your OTP is <b>123456</b></p>",
  // Text:    "Your OTP is 123456",
}
```

## Send and handle errors

```go theme={null}
if err := mailer.SendSingleMail(email); err != nil {
  // Errors may include:
  // - AWS credentials/region misconfigured
  // - Unverified sender/recipient (SES sandbox)
  // - Provider not supported
  // - Network/SES API errors
  log.Printf("mail send failed: %v", err)
}
```