Documentation

Introduction

Mailkit provides developer APIs backed by your Mailkit API key: push contacts into segments, and send transactional email through your verified domains (AWS SES).

Quickstart

Start with the minimum setup to send contacts from your app.

1. Go to Audience - Segments, create a segment, and copy the Segment ID.
2. Go to API Keys, create a key, and copy it once.
3. Add both values as environment variables in your app.
4. Send contacts to https://app.mailkit.app/api/contacts/native.
5. Optional: send transactional email from your backend with /api/emails/transactional.

Environment variables

MAILKIT_API_KEY=mk_live_...
MAILKIT_SEGMENT_ID=<YOUR_SEGMENT_ID_FROM_DASHBOARD>

Contacts API

Use /api/contacts/native with either Authorization: Bearer or x-api-key.

POST /api/contacts/native
Authorization: Bearer MAILKIT_API_KEY
Content-Type: application/json

{
  "segment_id": "<YOUR_SEGMENT_ID>",
  "email": "person@example.com"
}

{
  "segment_id": "<YOUR_SEGMENT_ID>",
  "emails": ["a@example.com", "b@example.com"]
}

Transactional email

Send a single message from your server (password resets, receipts, lifecycle hooks). Uses the same MAILKIT_API_KEY as contacts. Mail is delivered by AWS SES from an address on a verified domain in your Mailkit org (Domains in the dashboard).

POST /api/emails/transactional
Authorization: Bearer MAILKIT_API_KEY
Content-Type: application/json

{
  "to": "customer@example.com",
  "subject": "Your order is confirmed",
  "html": "<p>Thanks for your purchase.</p>",
  "text": "Thanks for your purchase.",
  "reply_to": "support@yourdomain.com",
  "from": "Your Store <orders@yourdomain.com>"
}

to, subject, and html are required. text, reply_to, and from are optional. If from is omitted, Mailkit uses noreply@ your first verified domain. If from is set, its domain must be verified for your org. Free plans include a small Mailkit attribution line in HTML (same as broadcasts). Sends count toward your monthly send cap.

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 to send contact');
console.log(json);

Transactional send:

const res = 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 (!res.ok) throw new Error((await res.json()).error || 'Send failed');

Supported now

• Create and revoke API keys from the dashboard.
• Create segments and copy segment IDs.
• Push one or many contacts into a segment via API.
• Send transactional email from your backend with a verified sending domain.
• Read success/failure using response status codes.