✉️ Send Emails

Prerequisites

A NotificationAPI account - sign up for free
An email notification configured in the dashboard (see Configure Notification)

Overview

Email notifications are one of the most important channels for user communication. NotificationAPI makes it easy to send personalized, professional emails with advanced features like parameters, attachments, CC/BCC, and tracking.

This guide covers everything you need to know about sending emails, from basic setup to advanced features.

Step 1: Verify Your Email Notification

If you haven’t already configured an email notification, follow our Configure Notification guide to create one with the Email channel enabled.

Once configured, note the Notification Type - you’ll need this in your code (e.g., welcome_email, order_confirmation).

Step 2: Install the SDK

Install the node package using one of the following package managers:

npm install notificationapi-node-server-sdk

yarn add notificationapi-node-server-sdk

pnpm add notificationapi-node-server-sdk

pip install notificationapi_python_server_sdk

composer require notificationapi/notificationapi-php-server-sdk

go get github.com/notificationapi-com/notificationapi-go-server-sdk

dotnet add package NotificationAPI --version 0.5.0

Add the following dependency to your Maven project:

<dependency>
    <groupId>com.notificationapi</groupId>
    <artifactId>notificationapi-java-server-sdk</artifactId>
    <version>0.2.0</version>
</dependency>

For optimal functionality, you’ll also need:

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>

Add the NotificationAPI class to your application - see the full Ruby implementation.

Step 3: Send a Basic Email

Here’s how to send a basic email notification:

import notificationapi from 'notificationapi-node-server-sdk';

// Initialize (default US region)
// For CA region: add 'https://api.ca.notificationapi.com' after CLIENT_SECRET
// For EU region: add 'https://api.eu.notificationapi.com' after CLIENT_SECRET
notificationapi.init('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Send email notification
notificationapi.send({
  type: 'welcome_email',
  to: {
    id: 'user123',
    email: 'user@example.com' // Required for email notifications
  },
  parameters: {
    firstName: 'John',
    companyName: 'Acme Corp'
  }
});

import asyncio
from notificationapi_python_server_sdk import notificationapi

# Initialize (default US region)
notificationapi.init("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

async def send_email():
    await notificationapi.send({
        "type": "welcome_email",
        "to": {
            "id": "user123",
            "email": "user@example.com"  # Required for email notifications
        },
        "parameters": {
            "firstName": "John",
            "companyName": "Acme Corp"
        }
    })

# Run the async function
asyncio.run(send_email())

use NotificationAPI\NotificationAPI;

// Initialize
$notificationapi = new NotificationAPI('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Send email notification
$notificationapi->send([
    "type" => "welcome_email",
    "to" => [
        "id" => "user123",
        "email" => "user@example.com"  // Required for email notifications
    ],
    "parameters" => [
        "firstName" => "John",
        "companyName" => "Acme Corp"
    ]
]);

package main

import (
    notificationapi "github.com/notificationapi-com/notificationapi-go-server-sdk"
)

func main() {
    // Initialize
    notificationapi.Init("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "https://api.notificationapi.com")

    // Prepare parameters
    parameters := make(map[string]interface{})
    parameters["firstName"] = "John"
    parameters["companyName"] = "Acme Corp"

    // Send email notification
    notificationapi.Send(
        notificationapi.SendRequest{
            Type: "welcome_email",
            To: notificationapi.User{
                Id:    "user123",
                Email: "user@example.com",  // Required for email notifications
            },
            Parameters: parameters,
        },
    )
}

using NotificationApi.Server;
using NotificationApi.Server.Models;

// Initialize
var notificationApi = new NotificationApiServer("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

// Create user
var user = new NotificationUser("user123")
{
    Email = "user@example.com"  // Required for email notifications
};

// Create parameters
var parameters = new Dictionary<string, object>
{
    { "firstName", "John" },
    { "companyName", "Acme Corp" }
};

// Send email notification
await notificationApi.Send(new SendNotificationData("welcome_email", user)
{
    Type = "welcome_email",
    To = user,
    Parameters = parameters
});

import com.notificationapi.NotificationApi;
import com.notificationapi.model.NotificationRequest;
import com.notificationapi.model.User;
import java.util.HashMap;
import java.util.Map;

// Initialize
NotificationApi api = new NotificationApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

// Create user
User user = new User("user123")
    .setEmail("user@example.com");  // Required for email notifications

// Create parameters
Map<String, Object> parameters = new HashMap<>();
parameters.put("firstName", "John");
parameters.put("companyName", "Acme Corp");

// Send email notification
NotificationRequest request = new NotificationRequest("welcome_email", user)
    .setType("welcome_email")
    .setTo(user)
    .setParameters(parameters);

String response = api.send(request);

# Initialize
notificationapi = NotificationAPI.new("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

# Send email notification
notificationapi.send({
  type: 'welcome_email',
  to: {
    id: 'user123',
    email: 'user@example.com'  # Required for email notifications
  },
  parameters: {
    firstName: 'John',
    companyName: 'Acme Corp'
  }
})

INFO

Get your CLIENT_ID and CLIENT_SECRET from your Environment Settings.

Step 4: Email Personalization with Parameters

Parameters allow you to inject dynamic content into your emails. You can use them in:

Email subject line
Email body content
Sender name

Parameter Example

// E-commerce order confirmation with parameters
notificationapi.send({
  type: 'order_confirmation',
  to: {
    id: 'customer456',
    email: 'customer@example.com'
  },
  parameters: {
    firstName: 'Sarah',
    orderNumber: 'ORD-789',
    orderTotal: '$149.99',
    itemsList: [
      { name: 'Wireless Headphones', price: '$99.99' },
      { name: 'Phone Case', price: '$29.99' },
      { name: 'Shipping', price: '$19.99' }
    ],
    trackingUrl: 'https://shipping.example.com/track/ABC123',
    estimatedDelivery: 'March 15, 2024'
  }
});

Using Parameters in Email Templates

In your email template designer, reference parameters using double curly braces:

Subject: Welcome {{firstName}}! Your order {{orderNumber}} is confirmed

Hi {{firstName}},

Thank you for your order! Here are the details:

Order Number: {{orderNumber}}
Total: {{orderTotal}}
Estimated Delivery: {{estimatedDelivery}}

You can track your package here: {{trackingUrl}}

Items in your order:
{{#each itemsList}}
- {{name}}: {{price}}
{{/each}}

Best regards,
The Team

TIP

You can use complex data structures in parameters, including arrays and objects. The email editor supports Handlebars templating syntax for loops and conditionals.

Testing and Production

Advanced Email Features

Email with Attachments

You can send files as email attachments:

notificationapi.send({
  type: 'invoice_email',
  to: {
    id: 'user123',
    email: 'user@example.com'
  },
  parameters: {
    invoiceNumber: 'INV-001',
    amount: '$99.99'
  },
  options: {
    email: {
      attachments: [
        {
          filename: 'invoice.pdf',
          url: 'https://example.com/files/invoice.pdf'
        }
      ]
    }
  }
});

await notificationapi.send({
    "type": "invoice_email",
    "to": {
        "id": "user123",
        "email": "user@example.com"
    },
    "parameters": {
        "invoiceNumber": "INV-001",
        "amount": "$99.99"
    },
    "options": {
        "email": {
            "attachments": [
                {
                    "filename": "invoice.pdf",
                    "url": "https://example.com/files/invoice.pdf"
                }
            ]
        }
    }
})

$notificationapi->send([
    "type" => "invoice_email",
    "to" => [
        "id" => "user123",
        "email" => "user@example.com"
    ],
    "parameters" => [
        "invoiceNumber" => "INV-001",
        "amount" => "$99.99"
    ],
    "options" => [
        "email" => [
            "attachments" => [
                [
                    "filename" => "invoice.pdf",
                    "url" => "https://example.com/files/invoice.pdf"
                ]
            ]
        ]
    ]
]);

CC and BCC Recipients

Send copies of your email to additional recipients:

notificationapi.send({
  type: 'team_update',
  to: {
    id: 'primary-user',
    email: 'primary@example.com'
  },
  options: {
    email: {
      ccAddresses: ['manager@example.com', 'team-lead@example.com'],
      bccAddresses: ['compliance@example.com']
    }
  },
  parameters: {
    projectName: 'Website Redesign',
    updateType: 'Status Update'
  }
});

await notificationapi.send({
    "type": "team_update",
    "to": {
        "id": "primary-user",
        "email": "primary@example.com"
    },
    "options": {
        "email": {
            "ccAddresses": ["manager@example.com", "team-lead@example.com"],
            "bccAddresses": ["compliance@example.com"]
        }
    },
    "parameters": {
        "projectName": "Website Redesign",
        "updateType": "Status Update"
    }
})

$notificationapi->send([
    "type" => "team_update",
    "to" => [
        "id" => "primary-user",
        "email" => "primary@example.com"
    ],
    "options" => [
        "email" => [
            "ccAddresses" => ["manager@example.com", "team-lead@example.com"],
            "bccAddresses" => ["compliance@example.com"]
        ]
    ],
    "parameters" => [
        "projectName" => "Website Redesign",
        "updateType" => "Status Update"
    ]
]);

Reply-To Addresses

Set custom reply-to addresses for two-way email communication:

notificationapi.send({
  type: 'support_ticket',
  to: {
    id: 'customer123',
    email: 'customer@example.com'
  },
  options: {
    email: {
      replyToAddresses: ['support@yourcompany.com']
    }
  },
  parameters: {
    ticketNumber: 'TKT-456',
    issueDescription: 'Login problems'
  }
});

await notificationapi.send({
    "type": "support_ticket",
    "to": {
        "id": "customer123",
        "email": "customer@example.com"
    },
    "options": {
        "email": {
            "replyToAddresses": ["support@yourcompany.com"]
        }
    },
    "parameters": {
        "ticketNumber": "TKT-456",
        "issueDescription": "Login problems"
    }
})

$notificationapi->send([
    "type" => "support_ticket",
    "to" => [
        "id" => "customer123",
        "email" => "customer@example.com"
    ],
    "options" => [
        "email" => [
            "replyToAddresses" => ["support@yourcompany.com"]
        ]
    ],
    "parameters" => [
        "ticketNumber" => "TKT-456",
        "issueDescription" => "Login problems"
    ]
]);

Custom From Address

Set a custom from address and sender name for your emails:

notificationapi.send({
  type: 'marketing_newsletter',
  to: {
    id: 'subscriber123',
    email: 'subscriber@example.com'
  },
  options: {
    email: {
      fromAddress: 'newsletter@yourcompany.com',
      fromName: 'Your Company Newsletter'
    }
  },
  parameters: {
    firstName: 'Sarah',
    productUpdate: 'New features are now available!'
  }
});

await notificationapi.send({
    "type": "marketing_newsletter",
    "to": {
        "id": "subscriber123",
        "email": "subscriber@example.com"
    },
    "options": {
        "email": {
            "fromAddress": "newsletter@yourcompany.com",
            "fromName": "Your Company Newsletter"
        }
    },
    "parameters": {
        "firstName": "Sarah",
        "productUpdate": "New features are now available!"
    }
})

$notificationapi->send([
    "type" => "marketing_newsletter",
    "to" => [
        "id" => "subscriber123",
        "email" => "subscriber@example.com"
    ],
    "options" => [
        "email" => [
            "fromAddress" => "newsletter@yourcompany.com",
            "fromName" => "Your Company Newsletter"
        ]
    ],
    "parameters" => [
        "firstName" => "Sarah",
        "productUpdate" => "New features are now available!"
    ]
]);

TIP

You can also set the fromAddress and fromName directly in the email template editor in your dashboard. When set in the template, you don’t need to specify them in your code. The options.email.fromAddress and options.email.fromName properties in your send request will override the template settings.

INFO

To use a custom fromAddress from your domain, you’ll need to verify your domain first. See our Domain Verification Guide for setup instructions. We strongly recommend you to verify your domain before sending emails from production.

Important Email Features

NotificationAPI provides comprehensive email functionality with advanced features:

High delivery through SPF, DKIM and DMARC - see docs
Compliant with Google’s and Yahoo’s email sender policies and best practices for high deliverability
Merge tags (injecting dynamic values into the email content) - see docs
Pre-built Unsubscribe Link and Web Page - see docs
Reply-to addresses for two-way email communication via options.email.replyToAddresses - see docs
File attachments via options.email.attachments - see docs
CC and BCC recipients via options.email.ccAddresses and options.email.bccAddresses - see docs

TIP

You DON’T need another 3rd-party email service like SendGrid or SES. Through our partnerships, We allocate and manage any required email infrastructure, even dedicated IPs, for you.

Google and Yahoo Bulk Sender Requirements

NotificationAPI automatically handles compliance with Google and Yahoo bulk sender requirements (read more on our blog):

Authentication: SPF, DKIM, DMARC configured automatically
Unsubscribe: One-click unsubscribe headers and links included per RFC 2369 and RFC 8058
Compliance: All requirements handled automatically in your account setup

Tracking and Analytics

NotificationAPI automatically tracks:

Delivery: Email successfully delivered to mail server
Bounces: Failed delivery attempts
Complaints: Users marking emails as spam
Opens and Clicks: Coming soon

View all analytics in your dashboard under Logs and Insights.

Need more help?

If you need help, reach out through our live chat or Slack community.