Sending Emails Programmatically

Notify’s API allows you to send emails directly from your application with minimal setup. In this guide, we’ll walk through the steps to programmatically send emails, including authentication, passing data to templates, and handling API responses.

1. Prerequisites

Before sending emails programmatically, make sure you’ve:

  1. Created a Company Profile on Notify.
  2. Retrieved your API Key from the Credentials page in your Notify dashboard.
  3. Created an Email Template that you want to use for sending emails.

2. Sending an Email Request

To send an email, you’ll need to make a POST request to the Notify API endpoint, including the recipient information, template ID, and any required dynamic data for placeholders in the email template.

API Endpoint

POST https://api.notify.com/send
Required Headers
Content-Type: application/json
Authorization: Bearer <your_api_key>

Example Request Body

The request body must include the following fields:

{
  "to": "recipient@example.com",
  "template_id": "template_abc123",
  "data": {
    "user_name": "John Doe",
    "order_number": "ORD-123",
    "items": ["Product A", "Product B"]
  }
}

Required Fields

| Field | Type | Description | | ------------- | ------ | --------------------------------------------------------- | | to | string | Recipient's email address | | template_id | string | The ID of the email template to use | | data | object | Key-value pairs of dynamic data for template placeholders |

Optional Fields

| Field | Type | Description | | ---------- | -------- | -------------------------------------------- | | cc | string[] | Array of CC email addresses | | bcc | string[] | Array of BCC email addresses | | reply_to | string | Custom reply-to email address | | subject | string | Override the template's default subject line |

3. Handling Responses

Successful Response

{
  "success": true,
  "message_id": "msg_xyz789",
  "status": "queued"
}

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_recipient",
    "message": "Invalid recipient email address"
  }
}

4. Code Examples

Node.js

const axios = require('axios');

async function sendEmail() {
  try {
    const response = await axios.post(
      'https://api.notify.com/send',
      {
        to: 'recipient@example.com',
        template_id: 'template_abc123',
        data: {
          user_name: 'John Doe',
          order_number: 'ORD-123'
        }
      },
      {
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'Bearer your_api_key_here'
        }
      }
    );

    console.log('Email sent:', response.data);
  } catch (error) {
    console.error('Error sending email:', error.response.data);
  }
}

Python

import requests

def send_email():
    url = 'https://api.notify.com/send'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your_api_key_here'
    }
    payload = {
        'to': 'recipient@example.com',
        'template_id': 'template_abc123',
        'data': {
            'user_name': 'John Doe',
            'order_number': 'ORD-123'
        }
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        print('Email sent:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error sending email:', e)

5. Best Practices

  1. Error Handling: Always implement proper error handling to catch and handle API errors gracefully.
  2. Rate Limiting: Be aware of API rate limits and implement appropriate retry mechanisms.
  3. Template Testing: Test your templates with various data combinations before sending to production.
  4. Validation: Validate email addresses and required data fields before making API calls.
  5. Logging: Maintain logs of sent emails and API responses for debugging and tracking.

6. Additional Resources

For more information or support, please contact our support team at support@notify.com.