API Reference

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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
  "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: '[email protected]',
  from: '[email protected]',
  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: "[email protected]",
  From: "[email protected]",
  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="[email protected]",
    from_="[email protected]",
    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' => '[email protected]',
    'from' => '[email protected]',
    '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": "[email protected]",
    "from": "[email protected]",
    "subject": "Hello",
    "body": "<p>Your message here</p>"
  }'

Documentation

SDKs

API Reference

Base URL

Authentication

Making requests

Send transactional email

Track event

Create contact

Response format

Public API endpoints (`/v1/*`)

Dashboard API endpoints

Error response

Rate limits

Error codes

Client libraries

Node.js

Go

Python

PHP

cURL

What’s next

​Base URL

​Authentication

​Making requests

​Send transactional email

​Track event

​Create contact

​Response format

​Public API endpoints (/v1/*)

​Dashboard API endpoints

​Error response

​Pagination

​Cursor-based pagination (contacts)

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

​Rate limits

​Error codes

​Client libraries

​Node.js

​Go

​Python

​PHP

​cURL

​What’s next

Base URL

Authentication

Making requests

Send transactional email

Track event

Create contact

Response format

Public API endpoints (`/v1/*`)

Dashboard API endpoints

Error response

Pagination

Cursor-based pagination (contacts)

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

Rate limits

Error codes

Client libraries

Node.js

Go

Python

PHP

cURL

What’s next