Your message here
" }' ``` ### Track event ```bash theme={null} 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 ```bash theme={null} 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: ```json theme={null} { "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}`): ```json theme={null} { "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: ```json theme={null} { "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](https://docs.mailglyph.com/api-reference/errors.md) for complete details and examples. ## Pagination The API uses two pagination styles, depending on endpoint: ### Cursor-based pagination (contacts) ```bash theme={null} 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) ```bash theme={null} 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](https://docs.mailglyph.com/api-reference/errors.md). ## Client libraries ### Node.js ```ts theme={null} 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: 'Your message here
' }); console.log(result.success, result.data.timestamp); ``` See [Node.js SDK docs](https://docs.mailglyph.com/sdks/nodejs/overview.md). ### Go ```go theme={null} import ( "context" "os" mailglyph "github.com/MailGlyph/mailglyph-go" ) ctx := context.Background() client := mailglyph.New(os.Getenv("MAILGLYPH_SECRET_KEY")) subject := "Hello" body := "Your message here
" 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](https://docs.mailglyph.com/sdks/go/overview.md). ### Python ```python theme={null} 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="Your message here
", ) print(result.timestamp) ``` See [Python SDK docs](https://docs.mailglyph.com/sdks/python/overview.md). ### PHP ```php theme={null} emails->send([ 'to' => 'user@example.com', 'from' => 'hello@your-verified-domain.com', 'subject' => 'Hello', 'body' => 'Your message here
', ]); echo $result->timestamp . PHP_EOL; ``` See [PHP SDK docs](https://docs.mailglyph.com/sdks/php/overview.md). ### cURL ```bash theme={null} 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": "Your message here
" }' ``` ## What's next * [Send your first email](https://docs.mailglyph.com/api-reference/public-api/sendEmail.md) * [Check error codes](https://docs.mailglyph.com/api-reference/errors.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.