Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notifuse.com/llms.txt

Use this file to discover all available pages before exploring further.

Transactional templates screenshot

​
Common Use Cases

- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations

​
Key Features

​
Automatic Contact Management

  • Contact Upsert: Contacts are automatically created or updated before sending
  • Profile Enrichment: Template data is automatically merged with existing contact profile information
  • Data Consistency: Ensures contact information is always current

​
Template Data Enrichment

When you send a transactional email, Notifuse automatically:
  1. Looks up the contact by email address in your workspace
  2. Merges your API data with the existing contact profile
  3. Enriches the template with the complete contact information
  4. Sends the personalized email with all available data
Example: If your API sends {"order_id": "12345"} but the contact profile contains {"first_name": "John", "last_name": "Doe"}, the template will have access to both the order data and the contact’s full profile.

​
Deduplication with External ID

  • Prevent Duplicates: Use external_id to prevent sending the same notification multiple times
  • Idempotent Requests: Notifications with the same external_id will only be sent once
  • Custom Identifiers: Use your own unique identifiers (order IDs, event IDs, etc.)
Example: Setting external_id: "order-12345" ensures that even if your system sends the same order confirmation multiple times, the email will only be delivered once.

​
Email Delivery Options

Configure email routing with flexible options:
  • From Name: Override the default sender display name
  • Subject: Override the template subject line (supports Liquid templating)
  • Reply-To: Set custom reply-to addresses
  • CC: Add carbon copy recipients
  • BCC: Include blind carbon copy recipients
  • Attachments: Attach files to emails (PDFs, images, documents, etc.)

​
API Endpoint

Send transactional emails using a simple POST request:

​
Request

curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'

​
Parameters

ParameterTypeRequiredDescription
workspace_idstringYesYour workspace identifier
notification.idstringYesTemplate identifier for the email
notification.external_idstringNoUnique identifier for deduplication
notification.channelsarrayYesMust include “email”
notification.contactobjectYesContact object with at least an email field
notification.dataobjectNoTemplate variables for email content
notification.metadataobjectNoTracking data (not available in templates)
notification.email_optionsobjectNoEmail routing configuration

​
Email Options

ParameterTypeDescription
from_namestringOverride default sender display name
subjectstringOverride template subject line (supports Liquid templating, max 255)
reply_tostringSet custom reply-to email address
ccarrayList of carbon copy recipients
bccarrayList of blind carbon copy recipients
attachmentsarrayFile attachments (max 20 files, 3MB per file, 10MB total)

​
Data vs Metadata

​
Template Variables (data)

The data object contains variables that will be available in your email templates: 
{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}
These can be used in templates as: {{ order_id }}, {{ total }}, {{ discount_code }}

​
Tracking Data (metadata)

The metadata object stores information for analytics and tracking but is not available in templates: 
{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}
Use metadata for internal tracking, analytics, and reporting purposes.

​
Email Attachments

Send files with your transactional emails such as invoices, receipts, tickets, or documents. Attachments are automatically deduplicated and stored efficiently.

​
Attachment Limits

  • Maximum files: 20 attachments per email
  • File size: 3MB per file
  • Total size: 10MB per email
  • Supported formats: All file types (PDF, PNG, JPEG, DOCX, etc.)

​
Attachment Parameters

ParameterTypeRequiredDescription
filenamestringYesName of the file (max 255 characters)
contentstringYesBase64-encoded file content
content_typestringNoMIME type (e.g., “application/pdf”), auto-detected if not provided
dispositionstringNo”attachment” (default) or “inline”

​
Example with PDF Invoice

{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}

​
Example with Multiple Attachments

{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}

​
Common Use Cases

  • Order Confirmations: Attach invoices and receipts
  • Booking Confirmations: Attach tickets and itineraries
  • Legal Documents: Attach contracts and agreements
  • Reports: Attach analytics reports and summaries
  • Certificates: Attach completion certificates and badges

​
SMTP Bridge

Notifuse includes a built-in SMTP bridge server that allows you to send transactional emails using standard SMTP clients instead of HTTP API calls. This is particularly useful when:
  • Legacy Systems: Integrating with existing applications that only support SMTP
  • Email Libraries: Using standard email libraries in any programming language
  • Framework Integration: Working with frameworks that have built-in SMTP support
  • Gradual Migration: Moving from existing email providers without changing application code

​
How It Works

The SMTP bridge server accepts emails via SMTP on port 587 (STARTTLS) or 465 (implicit TLS). The email body must contain a JSON payload matching the Transactional API format. Authentication is done using your workspace API credentials.

​
Sending Emails via SMTP

​
Authentication

  • Username: Your workspace API email (the email associated with your API key)
  • Password: Your workspace API key
  • Security: STARTTLS (port 587) or implicit TLS / SMTPS (port 465), depending on your SMTP_BRIDGE_TLS setting
  • Server: Your configured SMTP bridge host (e.g., smtp.yourdomain.com)

​
Email Format

The email body must be a JSON payload matching the Transactional API format: 
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}

​
Template Integration

​
Data Structure in Templates

Your templates have access to both API data and contact profile: 
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.

​
Complete Example

API Request: 
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}
Existing Contact Profile: 
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
Available in Template: 
Hi {{ contact.first_name }}!

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.

​
API Reference

​
Deduplication Examples

​
Order Confirmations

{
  "external_id": "order-12345-confirmation"
}

​
Password Resets

{
  "external_id": "pwd-reset-user123-20240101"
}

​
Welcome Emails

{
  "external_id": "welcome-user123"
}
Using consistent external_id patterns ensures that duplicate notifications are automatically prevented, even if your application sends multiple requests. For complete API documentation and additional parameters, see the API Reference.