Skip to main content

Quick Start

This guide walks you through sending your first email with Posta.

1. Start Posta​

Follow the Installation guide to start Posta with Docker Compose.

2. Log In and Create an API Key​

Log in to the dashboard at http://localhost:9000 with the admin credentials configured during setup.

Navigate to API Keys and create a new key:

curl -X POST http://localhost:9000/api/v1/users/me/api-keys \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Save the returned key — it will not be shown again.

3. Configure an SMTP Server​

Add your SMTP server:

curl -X POST http://localhost:9000/api/v1/users/me/smtp-servers \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "smtp.gmail.com",
    "port": 587,
    "username": "your-email@gmail.com",
    "password": "your-app-password",
    "encryption": "starttls"
  }'

4. Send Your First Email​

Use your API key to send an email:

curl -X POST http://localhost:9000/api/v1/emails/send \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Posta!",
    "html": "<h1>Welcome!</h1><p>Your Posta instance is working.</p>"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  }
}

5. Check Delivery Status​

Poll the status of your email:

curl http://localhost:9000/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer <your-api-key>"

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "sent",
    "retry_count": 0,
    "created_at": "2026-01-01T00:00:00Z",
    "sent_at": "2026-01-01T00:00:01Z"
  }
}

Using an SDK​

Instead of raw HTTP calls, use one of the official SDKs:

client := posta.New("http://localhost:9000", "your-api-key")

resp, err := client.SendEmail(&posta.SendEmailRequest{
    From:    "sender@yourdomain.com",
    To:      []string{"recipient@example.com"},
    Subject: "Hello from Posta!",
    HTML:    "<h1>Welcome!</h1>",
})

Next Steps​