Emailssary makes it easy to send emails programmatically using either our simple REST API or our TypeScript SDK. In this guide, we will walk through how to integrate Emailssary into your application and start sending emails in just a few steps.

Authentication

All API requests require an API key for authentication. You can find your API key in the dashboard settings. Pass the key in the Authorization header as a Bearer token:

Authorization: Bearer your-api-key

Sending Emails via the REST API

To send an email using the Emailssary REST API, send a POST request to the /v1/send endpoint with the required parameters in the request body.

Request Format

Endpoint:

POST /v1/send

Request Body:

{
  "recipient": "user@example.com",
  "email_type": "welcome_email",
  "data": {
    "username": "JohnDoe"
  }
}

Required Parameters

recipient: The email address of the recipient (required)
email_type: The identifier for the email template type (required)
data: Custom key-value pairs for template variables (optional)

Example cURL Request

curl -X POST https://api.emailssary.com/v1/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "user@example.com",
    "email_type": "welcome_email",
    "data": {"username": "JohnDoe"}
  }'

Response Format

{
  "success": true,
  "message": "Email sent successfully",
  "data": {
    "id": "uuid",
    "recipient": "user@example.com",
    "sentAt": "2025-03-17T12:34:56.789Z",
    "type": "welcome_email"
  }
}

Sending Emails Using the Emailssary SDK

For TypeScript projects, we recommend using the Emailssary SDK for easier integration.

Installation

First, install the SDK using npm:

npm install emailssary-sdk

Sending an Email

import { EmailssarySDK } from 'emailssary-sdk';

const sdk = new EmailssarySDK('your-api-key');

async function sendWelcomeEmail() {
  try {
    const response = await sdk.sendEmail({
      recipient: 'user@example.com',
      email_type: 'welcome_email',
      data: {
        username: 'JohnDoe'
      }
    });
    console.log('Email sent:', response);
  } catch (error) {
    console.error('Error sending email:', error);
  }
}

Handling Errors and Rate Limits

Common Errors

400 Bad Request: Missing required fields or invalid email type
401 Unauthorized: Invalid or missing API key
404 Not Found: Email settings not found for the specified type
429 Too Many Requests: Rate limit exceeded (max 10 requests/sec per API key)
500 Internal Server Error: Unexpected server issues

Handling Rate Limits

To prevent hitting rate limits, implement exponential backoff or queue requests when you receive a 429 Too Many Requests response.

Conclusion

Integrating Emailssary into your application is quick and straightforward, whether you use the REST API or the SDK. With just a few lines of code, you can start sending transactional emails efficiently. Try it today and make your customer communication seamless!

For more details, check out the full documentation at Emailssary API Docs.

How to Integrate the Emailssary SDK or REST API to Send Emails

Share this post