Description

APIMail is a powerful service that allows you to receive emails and forward them to your webhooks. It provides both SMTP and IMAP interfaces, making it easy to integrate email functionality into your applications.

Key features:

Usage

Register Email

Register an email address to receive webhook notifications.

curl -X POST https://apimail.de/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "webhook": "https://your-webhook-url.com"
  }'

Update Webhook

Update the webhook URL for a registered email address.

curl -X PUT "https://apimail.de/api/update?email=your@email.com" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": "https://new-webhook-url.com",
    "access_token": "your-access-token"
  }'

Access Emails via IMAP

Retrieve emails from a specific IMAP folder with optional filters. 

curl -X GET "https://apimail.de/api/imap/INBOX?newer_than=2024-03-01T00:00:00Z&older_than=2024-03-20T00:00:00Z&subject=Important&sender=john@example.com,jane@example.com" \
  -H "user: your-imap-username" \
  -H "password: your-imap-password" \
  -H "host: imap.example.com" \
  -H "port: 993" \
  -H "tls: true"

Query Parameters

Parameter Description Format Example
newer_than Nur E-Mails vom angegebenen Datum oder später anzeigen (ohne Uhrzeit) ISO 8601 (Datum) 2024-03-01
older_than Nur E-Mails vom angegebenen Datum oder früher anzeigen (ohne Uhrzeit) ISO 8601 (Datum) 2024-03-20
subject Search in email subjects (case-insensitive) String Important
sender Filter by sender email addresses Comma-separated list john@example.com,jane@example.com

Webhook Payload

When an email is received, the following payload is sent to your webhook: 

{
  "from": {
    "address": "sender@example.com",
    "name": "Sender Name"
  },
  "to": [
    {
      "address": "your@email.com",
      "name": "Your Name"
    }
  ],
  "subject": "Email Subject",
  "text": "Plain text content",
  "html": "HTML content",
  "attachments": [],
  "date": "2024-03-20T12:00:00.000Z"
}

Run on Docker

APIMail can be easily run using Docker. Here's how to get started:

1. Pull the Image

docker pull tobiasell/apimail:latest

2. Create a Configuration File

Create a config.yml file with your settings:

smtp:
  hostname: 0.0.0.0
  port: 25

mysql:
  host: mysql
  user: apimail
  password: your_password
  database: apimail
  port: 3306

3. Run with Docker Compose

Create a docker-compose.yml file:

version: '3'
services:
  apimail:
    image: tobiasell/apimail:latest
    ports:
      - "25:25"  # SMTP
      - "3000:3000"  # REST API
    volumes:
      - ./config.yml:/app/config.yml
    environment:
      - MYSQL_HOST=mysql
      - MYSQL_USER=apimail
      - MYSQL_PASSWORD=your_password
      - MYSQL_DATABASE=apimail
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=apimail
      - MYSQL_USER=apimail
      - MYSQL_PASSWORD=your_password
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

4. Start the Services

docker-compose up -d

5. Environment Variables

You can configure the service using these environment variables: 

MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=
MYSQL_DATABASE=apimail
MYSQL_PORT=3306
API_PORT=3000

6. Email Configuration

To receive emails, you have two options:

  1. MX Record Configuration: Set up an MX record for your domain pointing to the APIMail server. 
    # Example MX Record Configuration
yourdomain.com. IN MX 10 mail.apimail.de.
  2. Alternative Email Address: You can also use an email address in the format [yourname]@apimail.de without having to set up your own MX records.