API Reference

Complete documentation for the DeveloperLabs.email REST API

Authentication Sending Emails Templates Webhooks Analytics Domains SDKs

Authentication

All API requests require authentication using your API key. Include it in the Authorization header of every request.

Authorization: Bearer YOUR_API_KEY
Important: Keep your API key secure and never expose it in client-side code.

Getting Your API Key

You can find your API key in the DeveloperLabs.email dashboard under Account Settings.

Testing Your API Key

Verify your API key is working with this simple request:

curl -X GET "https://api.developerlabs.email/v1/account" \
-H "Authorization: Bearer YOUR_API_KEY"

Sending Emails

Send Email Endpoint

POST https://api.developerlabs.email/v1/send

Request Parameters

Parameter Type Required Description
to String or Array Yes Recipient email address(es)
from String Yes Sender email address (must be verified)
subject String Yes Email subject line
text String No* Plain text version of the email (required if no html)
html String No* HTML version of the email (required if no text)
cc String or Array No CC recipient(s)
bcc String or Array No BCC recipient(s)
reply_to String No Reply-to email address
attachments Array No Array of attachment objects

Example Request

const response = await fetch('https://api.developerlabs.email/v1/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    to: '[email protected]',
    from: '[email protected]',
    subject: 'Welcome to Our Service',
    html: '<h1>Welcome!</h1><p>Thanks for signing up...</p>',
    attachments: [
      {
        filename: 'document.pdf',
        content: 'BASE64_ENCODED_CONTENT',
        type: 'application/pdf'
      }
    ]
  })
});

Response

{
  "success": true,
  "message_id": "abc123xyz456",
  "timestamp": 1689876543,
  "recipients": ["[email protected]"]
}

Templates

Create and manage email templates that can be reused for common email types like welcome emails, receipts, etc.

Create Template

POST https://api.developerlabs.email/v1/templates

Request Body

{
  "name": "welcome_email",
  "subject": "Welcome to {{company}}",
  "html": "<h1>Welcome {{name}}!</h1><p>Thanks for joining {{company}}...</p>",
  "text": "Welcome {{name}}!\nThanks for joining {{company}}...",
  "variables": ["name", "company"]
}

Send Using Template

const response = await fetch('https://api.developerlabs.email/v1/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    to: '[email protected]',
    from: '[email protected]',
    template_id: 'welcome_email',
    variables: {
      name: 'John Doe',
      company: 'Acme Inc'
    }
  })
});

Webhooks

Receive real-time notifications about email events by configuring webhooks in your dashboard.

Supported Events

Event Description
sent Email was accepted by our servers
delivered Email was delivered to recipient's mail server
opened Recipient opened the email
clicked Recipient clicked a link in the email
bounced Email could not be delivered
complained Recipient marked email as spam

Webhook Payload Example

{
  "event": "delivered",
  "message_id": "abc123xyz456",
  "timestamp": 1689876543,
  "recipient": "[email protected]",
  "metadata": {
    "custom_id": "order_123",
    "user_id": "456"
  },
  "details": {
    "server": "mx.google.com",
    "response": "250 2.0.0 OK"
  }
}

Verifying Webhooks

Verify webhook requests come from DeveloperLabs.email by checking the signature header:

const crypto = require('crypto');

function verifyWebhook(req) {
  const signature = req.headers['x-developerlabs-signature'];
  const hmac = crypto.createHmac('sha256', 'YOUR_WEBHOOK_SECRET');
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');
  return signature === digest;
}

Official SDKs

JavaScript/Node.js

Install the Node.js SDK with npm:

npm install @developerlabs/email

Example usage:

const DeveloperLabs = require('@developerlabs/email');
const client = new DeveloperLabs('YOUR_API_KEY');

client.send({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Welcome</h1><p>Thanks for signing up!</p>'
}).then(console.log);
View Documentation

Python

Install the Python SDK with pip:

pip install developerlabs-email

Example usage:

from developerlabs_email import EmailClient

client = EmailClient(api_key="YOUR_API_KEY")

response = client.send_email(
    to="[email protected]",
    from_email="[email protected]",
    subject="Welcome!",
    html="<h1>Welcome</h1><p>Thanks for signing up!</p>"
)

print(response)
View Documentation