Documentation

Sending Email

API
Integration Guide

Send emails programmatically via our HTTP API or integrate with your existing email infrastructure using SMTP. Built for developers, designed for scale.

Prerequisites Required

Before you can send emails through Laneful, you must complete these essential setup steps:

1. Authenticate your domain (required)2. Choose and configure your lane type

New to Laneful? Start with our Getting Started guide.

REST API

Simple HTTP integration

SMTP Support

Standard email protocols

View Examples →

On this page

API
Integration

Overview

Laneful provides two methods for sending emails: HTTP API for programmatic access and SMTP for traditional email client integration. Check out our official SDKs for easier integration in 8 programming languages.

Sample Organization Endpoints

Below are sample endpoints. After you register and create an organization, you'll get your unique endpoints:

https://custom-endpoint.api.laneful.com
custom-endpoint.api.laneful.com

Note: These are sample endpoints. To get your actual organization endpoints, please register or log in to your account.

Quick Start

Send Your First Email

Use this example to send your first email via the HTTP API:

Sample code: Replace "custom-endpoint" with your actual organization endpoint after registration.

curl -k --request POST \
  --url http://custom-endpoint.api.laneful.com/v1/email/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "emails": [{
      "from": {
        "email": "noreply@yourdomain.com",
        "name": "Your App Name"
      },
      "to": [{
        "email": "user@example.com",
        "name": "User Name"
      }],
      "subject": "Welcome to Our Service",
      "text_content": "Hello,\n\nWelcome to our service! We're excited to have you on board.\n\nIf you have any questions, feel free to reach out to our support team.\n\nBest regards,\nThe Team"
    }]
  }'

Authentication

API Key Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Note: Replace YOUR_API_KEY with your actual API key from your account settings.

Important: The "from" email address must be from one of your verified domains.

HTTP API

Send Email Endpoint

Endpoint

POST /v1/email/send

Request Body

{
  "emails": [{
    "from": {
      "email": "sender@yourdomain.com",
      "name": "Sender Name"
    },
    "to": [{
      "email": "recipient@example.com", 
      "name": "Recipient Name"
    }],
    "subject": "Email Subject",
    "text_content": "Plain text content",
    "html_content": "<p>HTML content</p>",
    "reply_to": {
      "email": "reply@yourdomain.com",
      "name": "Reply Name"
    },
    "cc": [{"email": "cc@example.com", "name": "CC Name"}],
    "bcc": [{"email": "bcc@example.com", "name": "BCC Name"}],
    "attachments": [{
      "file_name": "document.pdf",
      "content": "base64-encoded-content",
      "content_type": "application/pdf"
    }],
    "headers": {
      "X-Custom-Header": "value"
    },
    "template_id": "template_123",
    "template_data": {
      "name": "John",
      "company": "Acme Corp"
    },
    "send_time": 1640995200,
    "webhook_data": {
      "campaign_id": "camp_123"
    },
    "tag": "newsletter"
  }]
}

Required Fields

  • • from - Valid sender email address
  • • At least one recipient in to, cc, or bcc
  • • Either text_content, html_content, or template_id

Response (200 OK)

{
  "status": "accepted"
}

Error Response (400/401)

{
  "error": "Invalid request or unauthorized"
}

Field Descriptions

For the full schema documentation, check the OpenAPI specification.

from

Sender email address and optional display name (required)

to

Primary recipients array. Maximum 1000 recipients total across to/cc/bcc

cc

Carbon copy recipients array (optional)

bcc

Blind carbon copy recipients array (optional)

subject

Email subject line (required)

text_content

Plain text email content

html_content

HTML email content for rich formatting

template_id

Use pre-built email templates with dynamic data

template_data

Data object to populate template variables using Handlebars syntax

attachments

Base64 encoded file content with content type and filename

headers

Custom email headers as key-value pairs

reply_to

Reply-to email address and optional display name

send_time

Unix timestamp for scheduled sending (max 72 hours future). Use 0 for immediate sending

webhook_data

Custom data sent to webhook endpoints (max 10 keys, 50 char keys, 100 char values)

tag

Label for organizing and tracking emails (max 100 characters)

tracking

Email tracking settings for opens, clicks, and unsubscribes

Tracking Settings Schema

The tracking object controls email analytics and unsubscribe behavior.

opensboolean

Track when recipients open emails (default: true)

clicksboolean

Track when recipients click links in emails (default: true)

unsubscribesboolean

Track unsubscribe events and add unsubscribe links (default: true)

unsubscribe_group_idinteger | null

Optional unsubscribe group ID. If not specified, uses global unsubscribe list. Ignored if unsubscribes is false.

Example

{
  "tracking": {
    "opens": true,
    "clicks": true,
    "unsubscribes": true,
    "unsubscribe_group_id": 123
  }
}

Email Templates

Using Templates with Handlebars

Templates support full Handlebars syntax for dynamic content including loops and conditions. Use template_id to reference a pre-built template and template_data to provide substitution values.

Template Example

{
  "emails": [{
    "from": {
      "email": "noreply@yourdomain.com",
      "name": "Your App"
    },
    "to": [{
      "email": "user@example.com",
      "name": "John Smith"
    }],
    "subject": "Welcome to Our Service",
    "template_id": "1234",
    "template_data": {
      "user_name": "John Smith",
      "company_name": "Acme Corp",
      "activation_link": "https://app.example.com/activate/abc123",
      "support_email": "support@yourdomain.com"
    }
  }]
}

Template Content (HTML)

<html>
<body>
  <h1>Welcome to {{company_name}}, {{user_name}}!</h1>
  
  <p>We're excited to have you on board. To get started, please activate your account:</p>
  
  <a href="{{activation_link}}" style="background: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">
    Activate Account
  </a>
  
  <p>If you have any questions, contact us at {{support_email}}</p>
  
  {{#if premium_user}}
  <div style="background: #f8f9fa; padding: 15px; border-radius: 5px;">
    <h3>Premium Features Available</h3>
    <p>As a premium user, you have access to advanced features!</p>
  </div>
  {{/if}}
  
  <footer>
    <p>Thanks,<br>The {{company_name}} Team</p>
  </footer>
</body>
</html>

Handlebars Features

{{variable}}

Simple variable substitution

{{#if condition}}...{{/if}}

Conditional blocks

{{#each items}}...{{/each}}

Iteration over arrays

{{#unless condition}}...{{/unless}}

Inverse conditional blocks

Template Data Format

The template_data field accepts a map of string keys to any values for substitutions:

"template_data": {
  "user_name": "John Smith",           // String
  "company_name": "Acme Corp",         // String
  "premium_user": true,                // Boolean
  "total_amount": 99.99,               // Number
  "items": ["item1", "item2"],         // Array
  "user_data": {"age": 25},            // Object
}

Note: Template_data accepts any JSON-serializable values including strings, numbers, booleans, arrays, and objects.

SMTP Configuration

SMTP Settings

Sample configuration: Your actual SMTP settings will be available after registration.

Server Settings

Host:custom-endpoint.api.laneful.com
Port:25/2525/587 (STARTTLS) or 465 (ENFORCE TLS)
Security:STARTTLS or SSL/TLS

Authentication

Username:apikey
Password:Your API Key

Note: Port 25 is often blocked by hosting providers. Use port 587 instead.

X-Laneful-API Header (Optional)

When sending via SMTP, you can add an optional X-Laneful-API header in JSON format to configure webhook data, tags, and tracking settings for individual messages.

Header Format

X-Laneful-API: {"webhook_data": {"campaign_id": "camp_123"}, "tag": "newsletter", "tracking": {"opens": true, "clicks": true, "unsubscribes": true, "unsubscribe_group_id": 123}}

Available Options

webhook_data

Custom data sent to webhook endpoints (max 10 keys, 50 char keys, 100 char values)

tag

Label for organizing and tracking emails (max 100 characters)

tracking

Override default tracking settings for this message (opens, clicks, unsubscribes)

Best Practices

✓ Do

  • • Use verified sender domains
  • • Include both text and HTML content
  • • Implement proper error handling
  • • Use meaningful subject lines
  • • Include unsubscribe links where required
  • • Test emails before production

✗ Don't

  • • Send from unverified domains
  • • Use misleading subject lines
  • • Send emails without proper authentication
  • • Ignore bounce and complaint handling
  • • Send bulk emails without proper consent
  • • Hardcode API keys in client-side code

Troubleshooting

Common Issues

401 Unauthorized

Check your API key and ensure it's correctly formatted in the Authorization header.

  • • Verify API key is active and not expired
  • • Ensure proper Bearer token format
  • • Check for any extra spaces or characters

Email not delivered

Verify sender domain and check recipient email validity.

  • • Ensure sender domain is verified
  • • Check recipient email format
  • • Review spam folder and filters

SMTP connection failed

Verify SMTP settings and network connectivity.

  • • Check host and port settings
  • • Verify TLS/SSL configuration
  • • Ensure firewall allows SMTP traffic