creobe/zapzap repository overview

⁠ZapZap - SMTP Relay Service

ZapZap is a lightweight SMTP relay service that uses Microsoft Graph API to relay emails. It is designed to be easy to deploy using Docker and Docker Compose. The service listens on port 25 and forwards emails using the credentials and configuration provided via environment variables.

⁠Features

• SMTP Relay: Forwards emails to Microsoft Graph API for delivery.
• Environment Variable Configuration: Configure the service using environment variables stored in a .env file.
• Auto-Restart: Configured to restart automatically unless stopped manually.

⁠Microsoft 365 Application Registration

Before using ZapZap, you'll need to register an application in Microsoft 365 (Azure AD) to obtain the necessary credentials.

⁠Steps to Register an Application in Microsoft 365

1. Go to Entra Portal:

   • Navigate to the Entra Portal⁠.

2. Register a New Application:

   • In the Entra Portal, go to Applications > App registrations > New registration.
   • Provide a name for your application (e.g., ZapZap SMTP Relay).
   • Set Supported account types to "Accounts in this organizational directory only (Single tenant)" unless you have a specific need for multi-tenant or personal accounts.
   • Click Register.

3. Record the Application (Client) ID and Directory (Tenant) ID:

   • Once registered, you'll be redirected to the application's overview page.
   • Copy the Application (client) ID and Directory (tenant) ID. You'll need these values for your .env file.

4. Create a Client Secret:

   • In the left-hand menu, select Certificates & secrets.
   • Under Client secrets, click New client secret.
   • Provide a description and set an expiration period.
   • Click Add and copy the value of the client secret. This will be used as the Relay__ClientSecret.

5. API Permissions:

   • In the left-hand menu, select API permissions.
   • Click Add a permission > Microsoft Graph > Application permissions.
   • Add the Mail.Send permission.
   • Click Grant admin consent to grant the required permissions.

6. Assign User ID:

   • Ensure that the user specified in Relay__UserId has the necessary permissions to send emails via the Microsoft Graph API. This can typically be the email address of an account within your organization.

⁠Usage

To get started with ZapZap, you'll need to set up a .env file with the required environment variables and use Docker Compose to deploy the service.

⁠1. Create a .env File

Create a .env file in the root of your project directory with the following variables:

Relay__ClientId=your-client-id
Relay__ClientSecret=your-client-secret
Relay__TenantId=your-tenant-id
Relay__UserId=your-user-id

• Relay__ClientId: The client ID for your Azure AD application.
• Relay__ClientSecret: The client secret for your Azure AD application.
• Relay__TenantId: Your Azure AD tenant ID.
• Relay__UserId: The user ID or email address used for relaying emails via Microsoft Graph API.

⁠2. Docker Compose Configuration

Ensure your docker-compose.yml file is configured as follows:

services:
  zapzap:
    image: creobe/zapzap:latest
    container_name: zapzap
    ports:
      - "25:25"
    environment:
      - Relay__ClientId=${Relay__ClientId}
      - Relay__ClientSecret=${Relay__ClientSecret}
      - Relay__TenantId=${Relay__TenantId}
      - Relay__UserId=${Relay__UserId}
    restart: unless-stopped

⁠3. Deploy with Docker Compose

To start the service, run:

docker-compose up -d

This command will start the ZapZap service in the background, listening on port 25, and configured using the environment variables from your .env file.

⁠Ports

• 25: The service listens on this port for incoming SMTP traffic.

⁠Environment Variables

• Relay__ClientId: Azure AD application client ID.
• Relay__ClientSecret: Azure AD application client secret.
• Relay__TenantId: Azure AD tenant ID.
• Relay__UserId: User ID or email address for relaying emails.

⁠Automatic Restart

The service is configured to automatically restart using Docker’s restart: unless-stopped policy. This ensures that the service remains running unless manually stopped.

⁠License

ZapZap is provided under the MIT License.