Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mailglyph.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://api.mailglyph.com
All API requests use this base URL.

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
  • Secret Key (sk_*) — Required for all endpoints except /v1/track
  • Public Key (pk_*) — Only works with /v1/track for client-side event tracking
Each API key set in the dashboard includes both a pk_* and sk_* key. You can create multiple key sets per workspace and scope them to specific domains.
Domain-scoped keys are enforced on sender-domain operations (for example /v1/send and SMTP sends). If a key is scoped, the sender domain must be in that key’s allowlist.
For key management details (create, edit scope, revoke), see API Keys.

​
Making requests

​
Send transactional email

curl -X POST https://api.mailglyph.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "body": "<p>Your message here</p>"
  }'

​
Track event

curl -X POST https://api.mailglyph.com/v1/track \
  -H "Authorization: Bearer pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "signed_up"
  }'

​
Create contact

curl -X POST https://api.mailglyph.com/contacts \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "subscribed": true,
    "data": {
      "firstName": "John",
      "plan": "pro"
    }
  }'

​
Response format

Response shapes differ by endpoint family.

​
Public API endpoints (/v1/*)

Public endpoints return a wrapped response: 
{
  "success": true,
  "data": {
    "contact": "cnt_abc123",
    "event": "evt_xyz789",
    "timestamp": "2025-11-30T10:30:00.000Z"
  }
}

​
Dashboard API endpoints

Dashboard endpoints usually return raw resource objects. Example (GET /contacts/{id}): 
{
  "id": "cnt_abc123",
  "email": "user@example.com",
  "subscribed": true,
  "createdAt": "2025-11-30T10:30:00.000Z",
  "updatedAt": "2025-11-30T10:30:00.000Z"
}
Campaign action endpoints (for example POST /campaigns, GET /campaigns/{id}) return wrapped payloads with success and data.

​
Error response

All errors include detailed information to help you debug issues: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 422,
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email",
        "code": "invalid_string"
      }
    ],
    "suggestion": "One or more fields have incorrect types. Check that strings are quoted, numbers are unquoted, and booleans are true/false."
  },
  "timestamp": "2025-11-30T10:30:00.000Z"
}
Error fields:
  • code — Machine-readable error code for programmatic handling
  • message — Human-readable description
  • statusCode — HTTP status code
  • requestId — Unique ID for debugging (include when contacting support)
  • errors — Field-level validation details (when applicable)
  • suggestion — Helpful guidance for fixing the error
See the Error Codes documentation for complete details and examples.

​
Pagination

The API uses two pagination styles, depending on endpoint:

​
Cursor-based pagination (contacts)

GET /contacts?limit=100&cursor=abc123
Parameters:
  • limit — Number of items per page (default: 20, max: 100)
  • cursor — Pagination cursor from previous response

​
Page-based pagination (campaigns, templates, workflow executions, segment contacts)

GET /campaigns?page=1&pageSize=20
Parameters:
  • page — Page number (default: 1)
  • pageSize — Items per page (default: 20, max: 100)

​
Rate limits

MailGlyph enforces reasonable rate limits to ensure service quality:
  • Email sending — 14 emails/second (default)
  • API requests — 1000 requests/minute per workspace
  • Bulk operations — Automatically queued for processing
If you exceed limits, you’ll receive a 429 Too Many Requests response.

​
Error codes

The API uses standard HTTP status codes along with machine-readable error codes: 400 Bad Request — Invalid request parameters or malformed request body 401 Unauthorized — Missing or invalid API key 403 Forbidden — Not authorized to access this resource or workspace disabled 404 Not Found — Resource doesn’t exist 422 Unprocessable Entity — Request validation failed (see errors array for details) 429 Too Many Requests — Rate limit exceeded 500 Internal Server Error — An unexpected error occurred (contact support with request ID) For a complete list of error codes and troubleshooting guidance, see the Error Codes documentation.

​
Client libraries

​
Node.js

import MailGlyph from 'mailglyph';

const client = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string);

const result = await client.emails.send({
  to: 'user@example.com',
  from: 'hello@your-verified-domain.com',
  subject: 'Hello',
  body: '<p>Your message here</p>'
});

console.log(result.success, result.data.timestamp);
See Node.js SDK docs.

​
Go

import (
  "context"
  "os"

  mailglyph "github.com/MailGlyph/mailglyph-go"
)

ctx := context.Background()
client := mailglyph.New(os.Getenv("MAILGLYPH_SECRET_KEY"))
subject := "Hello"
body := "<p>Your message here</p>"

result, err := client.Emails.Send(ctx, &mailglyph.SendEmailParams{
  To: "user@example.com",
  From: "hello@your-verified-domain.com",
  Subject: &subject,
  Body: &body,
})
if err != nil {
  panic(err)
}

println(result.Success, result.Data.Timestamp)
See Go SDK docs.

​
Python

from mailglyph import MailGlyph

client = MailGlyph("sk_your_secret_key")

result = client.emails.send(
    to="user@example.com",
    from_="hello@your-verified-domain.com",
    subject="Hello",
    body="<p>Your message here</p>",
)

print(result.timestamp)
See Python SDK docs.

​
PHP

<?php

use MailGlyph\MailGlyph;

$client = new MailGlyph($_ENV['MAILGLYPH_SECRET_KEY']);
$result = $client->emails->send([
    'to' => 'user@example.com',
    'from' => 'hello@your-verified-domain.com',
    'subject' => 'Hello',
    'body' => '<p>Your message here</p>',
]);

echo $result->timestamp . PHP_EOL;
See PHP SDK docs.

​
cURL

curl -X POST https://api.mailglyph.com/v1/send \
  -H "Authorization: Bearer $MAILGLYPH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@your-verified-domain.com",
    "subject": "Hello",
    "body": "<p>Your message here</p>"
  }'

​
What’s next