📧Email Dispatch

Learn how to send emails with document attachments through Docs-Dispatcher's email service.

Overview

This recipe covers:

Sending emails via SMTP providers
Attaching generated documents
Template-based email content
CC/BCC recipients
HTML and plain text emails
Complete examples in 4 languages

What You'll Learn

Structure email dispatch requests
Attach documents from templates
Configure SMTP providers
Handle multiple recipients
Email composition best practices
Complete working examples

Prerequisites

Docs-Dispatcher account with JWT
SMTP provider configured (Gmail, SendGrid, AWS SES, custom SMTP)
Email template created (optional)
Basic REST API knowledge

Email Service Overview

The email service supports:

✅ SMTP providers (Gmail, SendGrid, AWS SES, Mailgun, custom)
✅ Document attachments from templates
✅ HTML and plain text content
✅ CC and BCC recipients
✅ Reply-to addresses
✅ Custom headers
✅ Template-based content

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

Step 2: Prepare Email Request

Basic Email Structure

{
  "providerName": "sendgrid",
  "template": {
    "id": 130,
    "data": {
      "documentTitle": "Invoice INV-2026-001",
      "invoiceNumber": "INV-2026-001",
      "customer": {...},
      "items": [...],
      "total": 2400.00
    }
  },
  "email": {
    "from": {
      "email": "[email protected]",
      "name": "Your Company Billing"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Acme Corp Billing"
      }
    ],
    "subject": "Invoice INV-2026-001 - $2,400.00",
    "body": {
      "html": "<h1>Your Invoice is Ready</h1><p>Please find attached invoice INV-2026-001 for $2,400.00</p>",
      "text": "Your Invoice is Ready\n\nPlease find attached invoice INV-2026-001 for $2,400.00"
    },
    "attachments": [
      {
        "filename": "invoice-INV-2026-001.pdf",
        "fromTemplate": true
      }
    ]
  },
  "metadata": {
    "orderId": "ORD-123",
    "customerId": "CUST-789"
  }
}

Required Fields

Field

Type

Description

providerName

string

SMTP provider: sendgrid, ses, gmail, smtp

email.from

object

Sender email and name

email.to

array

Recipient email(s)

email.subject

string

Email subject line

email.body

object

HTML and/or text content

Optional Fields

Field

Type

Description

email.cc

array

CC recipients

email.bcc

array

BCC recipients

email.replyTo

object

Reply-to address

email.attachments

array

File attachments

template.id

number

Template for document attachment

Step 3: Email with Document Attachment

Attach Generated Document

curl -X POST https://api.docs-dispatcher.io/api/email \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "sendgrid",
    "template": {
      "id": 123,
      "data": {
        "invoiceNumber": "INV-2026-001",
        "date": "2026-02-13",
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]"
        },
        "items": [
          {
            "description": "Web Development",
            "total": 2000.00
          }
        ],
        "total": 2400.00
      }
    },
    "email": {
      "from": {
        "email": "[email protected]",
        "name": "Your Company"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Acme Corp"
        }
      ],
      "subject": "Invoice INV-2026-001",
      "body": {
        "html": "<p>Dear Acme Corp,</p><p>Please find attached your invoice for $2,400.00</p><p>Best regards,<br>Your Company</p>",
        "text": "Dear Acme Corp,\n\nPlease find attached your invoice for $2,400.00\n\nBest regards,\nYour Company"
      },
      "attachments": [
        {
          "filename": "invoice-INV-2026-001.pdf",
          "fromTemplate": true
        }
      ]
    }
  }'

Success Response:

{
  "success": true,
  "dispatchId": "disp_email_abc123",
  "providerResponse": {
    "messageId": "sg_msg_xyz789",
    "status": "sent",
    "sentAt": "2026-02-13T12:30:00Z"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/invoices/INV-2026-001.pdf",
    "size": 245678
  },
  "executionTime": 1.8
}

Step 4: Multiple Recipients (CC/BCC)

Email with CC and BCC

{
  "providerName": "sendgrid",
  "email": {
    "from": {
      "email": "[email protected]",
      "name": "Sales Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Customer"
      }
    ],
    "cc": [
      {
        "email": "[email protected]",
        "name": "Sales Manager"
      }
    ],
    "bcc": [
      {
        "email": "[email protected]",
        "name": "Archive"
      }
    ],
    "replyTo": {
      "email": "[email protected]",
      "name": "Support Team"
    },
    "subject": "Quote for Website Project",
    "body": {
      "html": "<p>Please find attached our quote</p>"
    }
  }
}

Complete Examples

curl (Complete Flow)

#!/bin/bash

# Authenticate
AUTH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }')

JWT_TOKEN=$(echo $AUTH_RESPONSE | jq -r '.token')

# Send email with invoice attachment
EMAIL_REQUEST='{
  "providerName": "sendgrid",
  "template": {
    "id": 123,
    "data": {
      "invoiceNumber": "INV-2026-001",
      "customer": {
        "name": "Acme Corp"
      },
      "total": 2400.00
    }
  },
  "email": {
    "from": {
      "email": "[email protected]",
      "name": "Your Company Billing"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Acme Corp"
      }
    ],
    "subject": "Invoice INV-2026-001",
    "body": {
      "html": "<p>Please find attached your invoice</p>",
      "text": "Please find attached your invoice"
    },
    "attachments": [
      {
        "filename": "invoice.pdf",
        "fromTemplate": true
      }
    ]
  }
}'

# Validate
VALIDATION=$(curl -s -X POST https://api.docs-dispatcher.io/api/email/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$EMAIL_REQUEST")

if [ "$(echo $VALIDATION | jq -r '.valid')" = "true" ]; then
  echo "Validation passed, sending email..."

  # Send email
  RESULT=$(curl -s -X POST https://api.docs-dispatcher.io/api/email \
    -u "$EMAIL:$PASSWORD" \
    -H "Content-Type: application/json" \
    -d "$EMAIL_REQUEST")

  if [ "$(echo $RESULT | jq -r '.success')" = "true" ]; then
    echo "Email sent successfully!"
    echo "Message ID: $(echo $RESULT | jq -r '.providerResponse.messageId')"
  else
    echo "Email failed:"
    echo $RESULT | jq
  fi
else
  echo "Validation failed:"
  echo $VALIDATION | jq '.errors'
fi

Node.js (Complete Flow)

const fetch = require('node-fetch');

const CONFIG = {
  templaterApiUrl: 'https://api.docs-dispatcher.io',
  dispatcherApiUrl: 'https://api.docs-dispatcher.io',
  email: '[email protected]',
  password: 'your-secure-password'
};

async function authenticate() {
  const response = await fetch(`${CONFIG.templaterApiUrl}/auth`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: CONFIG.email,
      password: CONFIG.password
    })
  });

  const data = await response.json();
  return data.token;
}

async function sendEmailWithInvoice(jwtToken) {
  const emailData = {
    providerName: 'sendgrid',
    template: {
      id: 123,
      data: {
        invoiceNumber: 'INV-2026-001',
        customer: { name: 'Acme Corp' },
        total: 2400.00
      }
    },
    email: {
      from: {
        email: '[email protected]',
        name: 'Your Company Billing'
      },
      to: [
        {
          email: '[email protected]',
          name: 'Acme Corp'
        }
      ],
      subject: 'Invoice INV-2026-001',
      body: {
        html: '<p>Please find attached your invoice</p>',
        text: 'Please find attached your invoice'
      },
      attachments: [
        {
          filename: 'invoice.pdf',
          fromTemplate: true
        }
      ]
    }
  };

  const response = await fetch(`${CONFIG.dispatcherApiUrl}/api/email`, {
    method: 'POST',
    headers: {
      'Authorization': authHeader,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(emailData)
  });

  return await response.json();
}

async function main() {
  try {
    const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;
const authHeader = createBasicAuthHeader(email, password);
// await authenticate();
    const result = await sendEmailWithInvoice(jwtToken);

    if (result.success) {
      console.log('Email sent successfully!');
      console.log('Message ID:', result.providerResponse.messageId);
    } else {
      console.error('Email failed:', result.message);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

PHP (Complete Flow)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

class EmailDispatcher {
    private $client;
    private $jwtToken;

    public function __construct() {
        $this->client = new Client();
    }

    public function authenticate($email, $password) {
        $response = $this->client->post('https://api.docs-dispatcher.io/auth', [
            'json' => [
                'email' => $email,
                'password' => $password
            ]
        ]);

        $data = json_decode($response->getBody(), true);
        $this->jwtToken = $data['token'];
        return $this->jwtToken;
    }

    public function sendEmailWithInvoice($emailData) {
        $response = $this->client->post('https://api.docs-dispatcher.io/api/email', [
            'headers' => [
                'Authorization' => 'Bearer ' . $this->jwtToken,
                'Content-Type' => 'application/json'
            ],
            'json' => $emailData
        ]);

        return json_decode($response->getBody(), true);
    }
}

$dispatcher = new EmailDispatcher();
$dispatcher->authenticate('[email protected]', 'your-password');

$emailData = [
    'providerName' => 'sendgrid',
    'template' => [
        'id' => 123,
        'data' => [
            'invoiceNumber' => 'INV-2026-001',
            'total' => 2400.00
        ]
    ],
    'email' => [
        'from' => [
            'email' => '[email protected]',
            'name' => 'Your Company'
        ],
        'to' => [
            [
                'email' => '[email protected]',
                'name' => 'Acme Corp'
            ]
        ],
        'subject' => 'Invoice INV-2026-001',
        'body' => [
            'html' => '<p>Please find attached your invoice</p>'
        ],
        'attachments' => [
            [
                'filename' => 'invoice.pdf',
                'fromTemplate' => true
            ]
        ]
    ]
];

$result = $dispatcher->sendEmailWithInvoice($emailData);

if ($result['success']) {
    echo "Email sent successfully!\n";
    echo "Message ID: {$result['providerResponse']['messageId']}\n";
} else {
    echo "Email failed\n";
}

Java (Complete Flow)

import java.net.URI;
import java.net.http.*;
import com.google.gson.Gson;
import java.util.*;

public class EmailDispatcher {
    private final HttpClient client;
    private final Gson gson;
    private String jwtToken;

    public EmailDispatcher() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    public void authenticate(String email, String password) throws Exception {
        Map<String, String> auth = new HashMap<>();
        auth.put("email", email);
        auth.put("password", password);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/auth"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(auth)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        Map data = gson.fromJson(response.body(), Map.class);
        this.jwtToken = (String) data.get("token");
    }

    public Map sendEmail(Map<String, Object> emailData) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/email"))
            .header("Authorization", authHeader)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(emailData)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        return gson.fromJson(response.body(), Map.class);
    }

    public static void main(String[] args) throws Exception {
        EmailDispatcher dispatcher = new EmailDispatcher();
        dispatcher.authenticate("[email protected]", "password");

        Map<String, Object> emailData = new HashMap<>();
        // Build email data...

        Map result = dispatcher.sendEmail(emailData);
        System.out.println("Email sent: " + result.get("success"));
    }
}

Provider-Specific Notes

SendGrid

Provider name: sendgrid

Features:

High deliverability
Email tracking
Click/open analytics
Template support

Configuration:

API key required
Verified sender identity

AWS SES

Provider name: ses

Features:

Low cost
High volume support
Email reputation monitoring

Configuration:

AWS credentials required
Domain verification needed

Gmail

Provider name: gmail

Features:

Easy setup
Good for small volumes
App password required

Configuration:

App-specific password
2FA recommended

Best Practices

1. Use Plain Text Alternative

Always provide both HTML and plain text:

{
  "body": {
    "html": "<h1>Invoice</h1><p>Amount: $2,400</p>",
    "text": "Invoice\n\nAmount: $2,400"
  }
}

2. Validate Email Addresses

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

3. Set Reply-To

{
  "replyTo": {
    "email": "[email protected]",
    "name": "Support Team"
  }
}

Error Handling

Common Errors

Invalid Recipient

{
  "error": "invalid_recipient",
  "message": "Invalid email address: invalid-email"
}

Provider Error

{
  "error": "provider_error",
  "message": "SendGrid API error: Invalid API key"
}

Next Steps

Invoice - Generate invoices to attach
Async Flow - Send emails asynchronously

Core Concepts

Summary

You've learned:

✅ Send emails with document attachments
✅ Configure SMTP providers
✅ Handle multiple recipients
✅ Complete implementations in 4 languages

Email dispatch makes document delivery seamless!

PreviousAsync Flow NextUpload Dispatch

Last updated 5 days ago

hashtagOverview

hashtagWhat You'll Learn

hashtagPrerequisites

hashtagEmail Service Overview

hashtagStep 1: Authentication

hashtagSetup Credentials

hashtagStep 2: Prepare Email Request

hashtagBasic Email Structure

hashtagRequired Fields

hashtagOptional Fields

hashtagStep 3: Email with Document Attachment

hashtagAttach Generated Document

hashtagStep 4: Multiple Recipients (CC/BCC)

hashtagEmail with CC and BCC

hashtagComplete Examples

hashtagcurl (Complete Flow)

hashtagNode.js (Complete Flow)

hashtagPHP (Complete Flow)

hashtagJava (Complete Flow)

hashtagProvider-Specific Notes

hashtagSendGrid

hashtagAWS SES

hashtagGmail

hashtagBest Practices

hashtag1. Use Plain Text Alternative

hashtag2. Validate Email Addresses

hashtag3. Set Reply-To

hashtagError Handling

hashtagCommon Errors

hashtagInvalid Recipient

hashtagProvider Error

hashtagNext Steps

hashtagRelated Recipes

hashtagCore Concepts

hashtagSummary

Overview

What You'll Learn

Prerequisites

Email Service Overview

Step 1: Authentication

Setup Credentials

Step 2: Prepare Email Request

Basic Email Structure

Required Fields

Optional Fields

Step 3: Email with Document Attachment

Attach Generated Document

Step 4: Multiple Recipients (CC/BCC)

Email with CC and BCC

Complete Examples

curl (Complete Flow)

Node.js (Complete Flow)

PHP (Complete Flow)

Java (Complete Flow)

Provider-Specific Notes

SendGrid

AWS SES

Gmail

Best Practices

1. Use Plain Text Alternative

2. Validate Email Addresses

3. Set Reply-To

Error Handling

Common Errors

Invalid Recipient

Provider Error

Next Steps

Related Recipes

Core Concepts

Summary