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.

The SDK throws typed errors that you can catch and handle.

​
Error classes

The Node.js SDK exports:
  • MailGlyphError
  • AuthenticationError
  • ValidationError
  • NotFoundError
  • RateLimitError
  • ApiError

​
Catch typed errors

import MailGlyph, {
  ApiError,
  AuthenticationError,
  MailGlyphError,
  NotFoundError,
  RateLimitError,
  ValidationError
} from 'mailglyph';

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

try {
  await client.contacts.get('missing-contact-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Contact not found');
    return;
  }

  if (error instanceof ValidationError) {
    console.error('Validation failed', error.details);
    return;
  }

  if (error instanceof AuthenticationError) {
    console.error('Check API key type or value');
    return;
  }

  if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after seconds:', error.retryAfter);
    return;
  }

  if (error instanceof ApiError) {
    console.error('Server/API error', error.status, error.details);
    return;
  }

  if (error instanceof MailGlyphError) {
    console.error('MailGlyph SDK error', error.status, error.message);
    return;
  }

  throw error;
}

​
Key-type mismatch example

events.track requires a public key and most other methods require a secret key. 
const secretClient = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string);

try {
  await secretClient.events.track({
    email: '[email protected]',
    event: 'signup'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error(error.message);
  }
}

​
Retry and timeout behavior

The SDK automatically retries transient failures:
  • Up to 3 retries for 429 and 5xx responses
  • Uses exponential backoff when retry-after is not present
  • Throws timeout errors when request duration exceeds the configured timeout
You can customize timeout in client config: 
const clientWithShortTimeout = new MailGlyph(process.env.MAILGLYPH_SECRET_KEY as string, {
  timeout: 10_000
});