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: The recipient’s email address.
template_id: The ID of the template you want to use.
data: An object containing dynamic values for placeholders in the template.
Here’s an example body structure:

{
  "to": "recipient@example.com",
  "template_id": "welcome-template",
  "data": {
    "name": "Recipient Name",
    "company": "Your Company",
    "message": "Welcome to our service!"
  }
}

Example Using Node.js Fetch

const sendEmail = async () => {
  try {
    const response = await fetch('https://api.notify.com/send', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer <your_api_key>`,
      },
      body: JSON.stringify({
        to: 'recipient@example.com',
        template_id: 'welcome-template',
        data: {
          name: 'Recipient Name',
          company: 'Your Company',
          message: 'Welcome to our service!',
        },
      }),
    });

    if (!response.ok) {
      throw new Error('Failed to send email');
    }

    const result = await response.json();
    console.log('Email sent successfully:', result);
  } catch (error) {
    console.error('Error sending email:', error);
  }
};

sendEmail();

This example sends an email using the template welcome-template, passing dynamic data (name, company, message) to replace placeholders in the template.

3. Dynamic Data and Placeholders Notify supports dynamic data in templates using placeholders. These placeholders are added in the template design as {placeholder_name} (e.g., {name}).

When making an API call, include the placeholder values in the data object:

name: Recipient Name
company: Your Company

Note: Ensure the data object keys match the placeholder names in your template. For example, {name} in the template should be passed as "name": "value" in the data object.

4. Handling API Responses Upon successfully sending an email, the API returns a response indicating the status. Handle this response in your application to confirm delivery or handle errors.

Success Response

On a successful email send, Notify returns a 200 OK status with a response body that includes:

status: success
message: Details about the email send event
email_id: A unique ID for tracking the email in Notify logs

Example response:

{
"status": "success",
"message": "Email sent successfully",
"email_id": "12345-abcde"
}

Error Handling

If the API encounters an error (e.g., invalid template ID or missing data), it returns a 4xx or 5xx status code with an error message. Handle errors by checking the response status and logging the error.

Example error response:

{
"status": "error",
"message": "Invalid template ID"
}

5. Testing Your Setup To verify your setup:

Use a test email address and call the send endpoint to see if the email is delivered successfully.

Check the Email Logs in the Notify dashboard for the email’s status and delivery details.

Make adjustments to your code or template as needed based on the test results.