# Mailkit Docs (Basics)

Last updated: 2026-04-16

## Overview
Use Mailkit API keys to (1) push contacts into a segment and (2) send transactional email from your backend.
Sending uses AWS SES and requires a verified domain on the org (see product setup docs).

## Required setup
1. In Mailkit dashboard:
   - Create a Segment in Audience > Segments
   - Create an API Key in API Keys
2. Save these env vars:
   - MAILKIT_API_KEY
   - MAILKIT_SEGMENT_ID
3. Send contacts to:
   - https://app.mailkit.app/api/contacts/native

## Endpoint
POST /api/contacts/native

### Headers
- Authorization: Bearer <MAILKIT_API_KEY>
  OR
- x-api-key: <MAILKIT_API_KEY>
- Content-Type: application/json

### Body (single email)
{
  "segment_id": "<YOUR_SEGMENT_ID>",
  "email": "person@example.com"
}

### Body (bulk)
{
  "segment_id": "<YOUR_SEGMENT_ID>",
  "emails": ["a@example.com", "b@example.com"]
}

## Response
200:
{
  "ok": true,
  "imported": 2,
  "segment_id": "..."
}

## Errors
- 400 invalid payload or invalid segment_id for API key org
- 401 missing or invalid API key
- 402 plan usage limit reached
- 500 internal/database error

## Transactional email
POST /api/emails/transactional

Base URL: use https://app.mailkit.app for production; if integrating against another deployment (staging, self-hosted), replace the host with that deployment's origin (same paths under /api).

Prerequisite: the Mailkit org must have at least one domain verified under Domains (dashboard). Otherwise omitting "from" fails (no default), and setting "from" fails if that address's domain is not verified. SES must allow sending (org out of AWS SES sandbox for arbitrary recipients).

Same auth as contacts: Authorization: Bearer <MAILKIT_API_KEY> OR x-api-key.

### Body
- to (string, required): recipient email
- subject (string, required)
- html (string, required): HTML body
- text (string, optional): plain-text part
- reply_to (string, optional)
- from (string, optional): bare email or "Display Name <email@domain>". Domain must be verified for the API key's org. If omitted, uses noreply@first verified domain.

### Behavior
- Delivered via AWS SES (not Resend).
- Counts toward the org's monthly send cap; 402 when blocked (same as contacts import limits style).
- Free tier may append a small Mailkit attribution footer to HTML (badge), same as marketing sends.

### Response
200: { "ok": true }

### Errors
- 400 invalid body, unverified from domain, or no verified domain when from omitted
- 401 missing or invalid API key
- 402 send cap / billing gate (cannot send)
- 502 SES or transport error (body contains error message)

## Node.js example
const res = await fetch('https://app.mailkit.app/api/contacts/native', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILKIT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    segment_id: process.env.MAILKIT_SEGMENT_ID,
    email: 'person@example.com'
  })
});

const json = await res.json();
if (!res.ok) throw new Error(json.error || 'Failed');

Transactional example:
const tx = await fetch('https://app.mailkit.app/api/emails/transactional', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILKIT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Order confirmed',
    html: '<p>Thank you.</p>'
  })
});
if (!tx.ok) throw new Error((await tx.json()).error || 'Transactional send failed');

## What is supported now
- Generate and revoke API keys
- Manage segments and segment IDs
- Add single or bulk contacts to a segment
- Send one transactional email per request from server-side code