Skip to content
mailiam Docs

Getting Started with SDKs

Get started with mailiam SDKs in under 5 minutes.

Prerequisites

Section titled “Prerequisites”
  • Node.js 16.0.0 or higher (for @mailiam/node)
  • mailiam CLI installed (npm install -g mailiam)
  • A verified domain in mailiam

Installation

Section titled “Installation”

Choose the SDK that fits your use case:

For Server-Side Email Sending

Section titled “For Server-Side Email Sending”
Terminal window
npm install @mailiam/node

For Browser-Side Forms

Section titled “For Browser-Side Forms”
Terminal window
npm install @mailiam/client

Get Your API Key

Section titled “Get Your API Key”

Server-Side Key (for @mailiam/node)

Section titled “Server-Side Key (for @mailiam/node)”
Terminal window
mailiam keys create --name "Production Server" --type usage

Copy the key that starts with mlm_sk_...

Public Key (for @mailiam/client)

Section titled “Public Key (for @mailiam/client)”
Terminal window
mailiam keys create --name "Website Forms" --type public --domain mycompany.com

Copy the key that starts with mlm_pk_...

Send Your First Email

Section titled “Send Your First Email”

Using @mailiam/node

Section titled “Using @mailiam/node”

Create a file send-email.js:

import { mailiam } from '@mailiam/node';


const mailiam = new mailiam({
  apiKey: process.env.MAILIAM_API_KEY
});


async function sendWelcomeEmail() {
  try {
    const result = await mailiam.emails.send({
      from: 'hello@mycompany.com',
      to: 'customer@example.com',
      subject: 'Welcome to Our Service',
      html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
      text: 'Welcome! Thanks for joining us.'
    });


    console.log('Email sent successfully!');
    console.log('Message ID:', result.messageId);
  } catch (error) {
    console.error('Failed to send email:', error.message);
  }
}


sendWelcomeEmail();

Run it:

Terminal window
MAILIAM_API_KEY=mlm_sk_... node send-email.js

Submit Your First Form

Section titled “Submit Your First Form”

Using @mailiam/client

Section titled “Using @mailiam/client”

Create a simple HTML page:

<!DOCTYPE html>
<html>
<head>
  <title>Contact Form</title>
</head>
<body>
  <form id="contactForm">
    <input name="name" placeholder="Your Name" required>
    <input name="email" type="email" placeholder="Your Email" required>
    <textarea name="message" placeholder="Your Message" required></textarea>
    <button type="submit">Send</button>
  </form>
  <div id="status"></div>


  <script type="module">
    import { mailiamClient } from 'https://esm.sh/@mailiam/client';


    const client = new mailiamClient({
      publicKey: 'mlm_pk_...' // Optional
    });


    document.getElementById('contactForm').addEventListener('submit', async (e) => {
      e.preventDefault();


      const formData = new FormData(e.target);
      const data = Object.fromEntries(formData.entries());


      try {
        await client.submitForm('mycompany.com', data);
        document.getElementById('status').textContent = 'Message sent!';
        e.target.reset();
      } catch (error) {
        document.getElementById('status').textContent = 'Error: ' + error.message;
      }
    });
  </script>
</body>
</html>

Environment Variables

Section titled “Environment Variables”

Store your API keys securely in environment variables:

Node.js (.env file)

Section titled “Node.js (.env file)”
Terminal window
MAILIAM_API_KEY=mlm_sk_your_key_here

Next.js

Section titled “Next.js”
Terminal window
# Server-side only
MAILIAM_API_KEY=mlm_sk_your_key_here


# Client-side safe
NEXT_PUBLIC_MAILIAM_PUBLIC_KEY=mlm_pk_your_key_here

Vercel/Netlify

Section titled “Vercel/Netlify”

Add environment variables in your hosting platform’s dashboard.

TypeScript Support

Section titled “TypeScript Support”

Both SDKs include full TypeScript definitions:

import { mailiam, type SendEmailRequest } from '@mailiam/node';


const mailiam = new mailiam({
  apiKey: process.env.MAILIAM_API_KEY!
});


const emailRequest: SendEmailRequest = {
  from: 'hello@mycompany.com',
  to: 'customer@example.com',
  subject: 'Welcome',
  html: '<h1>Hello</h1>'
};


await mailiam.emails.send(emailRequest);

Error Handling

Section titled “Error Handling”

SDKs provide specific error types:

import {
  mailiam,
  AuthenticationError,
  RateLimitError,
  ValidationError
} from '@mailiam/node';


try {
  await mailiam.emails.send({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof ValidationError) {
    console.error('Invalid email data:', error.details);
  }
}

Next Steps

Section titled “Next Steps”

For @mailiam/node:

Section titled “For @mailiam/node:”

For @mailiam/client:

Section titled “For @mailiam/client:”

Examples:

Section titled “Examples:”