Documentation

Get up and running with GetMailer in 3 simple steps.

1. Add and verify your domain

In your dashboard, add your sending domain and configure the DNS records we provide (SPF, DKIM, DMARC).

2. Create an API key

Go to API Keys and create a new key. Each API key must be linked to at least one verified domain.

3. Send your first email

curl -X POST https://getmailer.co/api/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from GetMailer!",
    "html": "<h1>Welcome!</h1><p>Your first email.</p>"
  }'

API keys authenticate your requests to the GetMailer API. Each key must be linked to one or more verified domains.

Key Format

API keys start with gm_ followed by a unique identifier.

Domain Linking

When you create an API key, you must select which domains it can send from. This ensures emails are only sent from verified domains you control.

To send emails, you need to verify ownership of your domain and configure email authentication.

Required DNS Records

• SPF - Authorizes GetMailer to send on your behalf
• DKIM - Cryptographically signs your emails
• DMARC - Protects against spoofing (recommended)

After adding your domain in the dashboard, we provide the exact DNS records to add. Verification typically completes within minutes once records propagate.

All API requests require authentication using a Bearer token in the Authorization header.

Requests without a valid API key will receive a 401 Unauthorized response.

Send transactional emails using our REST API.

Endpoint

Request Body

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your subject line",
  "html": "<h1>Hello!</h1>",
  "text": "Hello! (plain text fallback)",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "replyTo": "[email protected]",
  "tags": ["welcome", "onboarding"],
  "headers": {
    "X-Custom-Header": "value"
  }
}

Parameters

Response

{
  "id": "clx1abc123def456",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your subject line",
  "status": "sent",
  "tags": ["welcome", "onboarding"]
}

Retrieve a paginated list of emails you have sent.

Endpoint

Query Parameters

• limit - Number of results (default: 50, max: 100)
• cursor - Pagination cursor from previous response

Response

{
  "emails": [
    {
      "id": "clx1abc123def456",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Hello",
      "status": "delivered",
      "createdAt": "2024-01-15T10:30:00Z",
      "sentAt": "2024-01-15T10:30:01Z"
    }
  ],
  "nextCursor": "clx1abc123def457"
}

Use templates to create reusable email designs with dynamic variables.

Using a Template

{
  "from": "[email protected]",
  "to": "[email protected]",
  "templateId": "your-template-id",
  "variables": {
    "name": "John",
    "company": "Acme Inc",
    "resetLink": "https://example.com/reset/abc123"
  }
}

Variable Syntax

Use double curly braces in your templates:

<p>Hello {{name}},</p>
<p>Click <a href="{{resetLink}}">here</a> to reset your password.</p>

Schedule emails to be sent at a future time using the scheduledAt parameter.

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Scheduled reminder",
  "html": "<p>This is your scheduled reminder!</p>",
  "scheduledAt": "2024-01-20T09:00:00Z"
}

API requests are rate limited to ensure fair usage and system stability.

Response Headers

• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Seconds until rate limit resets

When rate limited, you will receive a 429 Too Many Requests response. Wait for the reset time before retrying.

Prevent duplicate emails by including an idempotency key with your requests.

curl -X POST https://getmailer.co/api/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{ ... }'

If you retry a request with the same idempotency key, we return the original response instead of creating a duplicate email. Keys are valid for 24 hours.

The API uses standard HTTP status codes and returns JSON error responses.

Status Codes

Error Response

{
  "error": "Description of what went wrong",
  "code": "ERROR_CODE"
}

Receive real-time notifications about email events by configuring webhooks in your dashboard.

Configuration

Go to Settings → Webhooks in your dashboard to add your webhook URL. We will POST event data to your endpoint as events occur.

Payload

{
  "event": "email.delivered",
  "emailId": "clx1abc123def456",
  "timestamp": "2024-01-15T10:30:05Z",
  "data": {
    "to": "[email protected]",
    "subject": "Hello from GetMailer"
  }
}