# Postmark Email Service

This document provides information on how to use the Postmark Email Service in the QuitSure application.

## Overview

The Postmark Email Service is a reusable library for sending transactional emails using Postmark templates. It provides a simple and consistent way to send emails throughout the application.

## Configuration

The Postmark Email Service is configured in the `config/postmark.php` file. This file contains the following configuration options:

- `token`: The Postmark API token used to authenticate with the Postmark API.
- `default_stream`: The default message stream to use when sending emails.
- `from_name`: The default sender name to use when sending emails.
- `from_email`: The default sender email address to use when sending emails.
- `templates`: A list of predefined email templates that can be used in the application.

You can configure these options in your `.env` file:

```
POSTMARK_TOKEN=your_postmark_server_token
POSTMARK_DEFAULT_STREAM=outbound
```

## Usage

### Using the Facade

The easiest way to use the Postmark Email Service is through the `Postmark` facade:

```php
use App\Facades\Postmark;

// Send an email using a template
Postmark::sendTemplate(
    'recipient@example.com',
    'template-alias',
    [
        'name' => 'John Doe',
        'unsubscribe_link' => 'https://example.com/unsubscribe'
    ],
    'Sender Name',
    'sender@example.com',
    'tag',
    'message-stream'
);

// Send an email using a predefined template
Postmark::sendPredefinedTemplate(
    'recipient@example.com',
    'welcome',
    [
        'name' => 'John Doe',
        'unsubscribe_link' => 'https://example.com/unsubscribe'
    ]
);

// Send a welcome email
Postmark::sendWelcomeEmail(
    'recipient@example.com',
    'John Doe',
    'https://example.com/unsubscribe'
);
```

### Using the Helper Functions

The Postmark Email Service also provides helper functions for sending emails:

```php
// Send an email using a template (backward-compatible with the old function)
sendTemplateEmailPostMark(
    'recipient@example.com',
    'template-alias',
    [
        'name' => 'John Doe',
        'unsubscribe_link' => 'https://example.com/unsubscribe'
    ],
    'Sender Name',
    'sender@example.com',
    'tag',
    'message-stream'
);

// Send a welcome email
sendWelcomeEmail(
    'recipient@example.com',
    'John Doe',
    'https://example.com/unsubscribe'
);
```

### Using the Service Directly

You can also inject the `PostmarkService` into your classes and use it directly:

```php
use App\Services\PostmarkService;

class MyClass
{
    protected $postmarkService;

    public function __construct(PostmarkService $postmarkService)
    {
        $this->postmarkService = $postmarkService;
    }

    public function sendEmail()
    {
        $this->postmarkService->sendTemplate(
            'recipient@example.com',
            'template-alias',
            [
                'name' => 'John Doe',
                'unsubscribe_link' => 'https://example.com/unsubscribe'
            ],
            'Sender Name',
            'sender@example.com',
            'tag',
            'message-stream'
        );
    }
}
```

## Adding New Templates

To add a new template, you need to:

1. Create the template in the Postmark dashboard.
2. Add the template to the `templates` array in the `config/postmark.php` file:

```php
'templates' => [
    'welcome' => [
        'alias' => 'coach-intro-template',
        'tag' => 'coach-intro',
        'stream' => 'prod-other-emails',
    ],
    'new-template' => [
        'alias' => 'new-template-alias',
        'tag' => 'new-template-tag',
        'stream' => 'new-template-stream',
    ],
],
```

3. You can then use the template with the `sendPredefinedTemplate` method:

```php
Postmark::sendPredefinedTemplate(
    'recipient@example.com',
    'new-template',
    [
        'variable1' => 'value1',
        'variable2' => 'value2'
    ]
);
```

## Error Handling

The Postmark Email Service logs all email sending attempts, both successful and failed. You can check the logs for any errors that occur during email sending.

Successful email sends are logged with the `info` level, while failed email sends are logged with the `error` level.

## Integration with Social Login

The Postmark Email Service is integrated with the social login API to send welcome emails when new users are created. This is done in the `UserService::createNewUser` method:

```php
// Send welcome email
if (isset($postData["vEmail"]) && $this->isValidEmail($postData["vEmail"])) {
    $firstName = explode(' ', trim($postData["VName"] ?? "Fighter"))[0];
    sendWelcomeEmail(
        $postData["vEmail"],
        $firstName,
        config('app.web_base_url') . 'emails/unsubscribe-request/' . $this->encryptData($userId)
    );
}
```

This sends a welcome email to the user using the `welcome` template defined in the `config/postmark.php` file.