> For the complete documentation index, see [llms.txt](https://docs.fastphoenix.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastphoenix.pro/features/mailgun.md).

# Mailgun

#### Mailgun Setup Tutorial

Fast Phoenix includes Mailgun integration for sending transactional emails and running email campaigns. Follow these steps to configure Mailgun for your project.

***

**Step 1: Prepare Your Environment Variables**

Fast Phoenix uses environment variables to manage Mailgun configuration. You will also have to set this in your config.ex file under config :mailgun.. As the module requires the variables at compile time. Open your `.env` file and ensure the following variables are set:

```env
# Mailgun Configuration
MAILGUN_API_KEY=your_mailgun_api_key
MAILGUN_DOMAIN=https://api.mailgun.net/v3/your-domain.com
```

Replace the placeholder values with your actual Mailgun API key and domain.

***

**Step 2: Set Up Mailgun Account**

1. **Create a Mailgun Account**\
   Sign up or log in to your [Mailgun Dashboard](https://www.mailgun.com/).
2. **Add Your Domain**
   * Navigate to *Domains* and add your sending domain (e.g., `your-domain.com`).
   * Follow the DNS setup instructions provided by Mailgun to verify your domain.
3. **Get Your API Key**
   * Once your domain is verified, go to *API Keys* in your account settings.
   * Copy your private API key and paste it into the `MAILGUN_API_KEY` field in your `.env` file.

***

**Step 3: Test Mailgun Integration**

1. **Send a Test Email**\
   In your Phoenix application, you can send a test email to verify the setup:

   ```elixir
   defmodule PhxSaas.Mailer do
     use Mailgun.Client,
       domain: Application.get_env(:mailgun, :domain),
       key: Application.get_env(:mailgun, :api_key)

     alias PhxSaas.Templates.EmailTemplates

     def deliver_user_instructions(recipient, subject, body) do

       case send_email(
           to: recipient,
           from: "#{Application.get_env(:phx_saas, :saas_name)} <mailgun@#{Application.get_env(:phx_saas, :domain)}>",
           subject: subject,
           html: body
       ) do
         {:ok, _metadata} -> {:ok, _metadata}
         {:error, _reason} -> notify_admin(subject, recipient)
         :ok -> IO.puts "Email sent successfully"
       end
     end

     def notify_admin(subject, user) do
       {:ok, _metadata} =
         send_email(
             to: Application.get_env(:phx_saas, :email),
             from: "#{Application.get_env(:phx_saas, :saas_name)} <mailgun@#{Application.get_env(:phx_saas, :domain)}>",
             subject: subject,
             text: "Failed to send instructions to user: #{user.email}"
           )
     end
   end

   PhxSaas.Mailer.deliver_user_instructions("recipient@gmail.com", "Test", """<h1> This is a test email </h1>""")
   ```
2. **Verify the Email**\
   Check the recipient's inbox or your Mailgun logs to confirm the email was sent successfully.

***

**Step 4: Configure Email Templates**

Fast Phoenix supports customizable email templates stored in the database. You can manage them directly from the admin interface:

1. Navigate to the admin dashboard.
2. Select *Email Templates* to view, create, or edit templates.

***

**Step 5: Bulk Email Campaigns**

Use Fast Phoenix emailing capabilities to send bulk emails directly from the admin dashboard:

1. Set filters for user types to target specific audiences.
2. Compose your email campaign using a custom template.
3. Launch the campaign, and track its performance in the Mailgun Dashboard.