Amtech Mail Sender SDK Documentation


Overview

The Mail Sender SDK provides an easy way to send emails through an API, utilizing Node.js and browser environments. The SDK abstracts the complexity of sending emails and handles API calls to send email messages in both server-side (Node.js) and client-side (browser) applications. It can be used to send customized email content such as subject, body, recipient, and sender information to an API endpoint that processes email sending


Key Features


  • Node.js & Browser Support: Works in both server-side Node.js environments and client-side browser environments.
  • API Integration: Seamlessly connects to the mail sending API.
  • Error Handling: Handles API errors gracefully with clear error messages.
  • Cross-Platform: Automatically detects the environment (Node.js or browser) and adapts the fetch API accordingly.

To use this SDK, you need an API key. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Installation


1. Install the SDK

To use the SDK in a Node.js environment, run: 

npm install mail-sender-sdk

For browser environments, download the SDK and simply include the script in your HTML or use it in a module format.

2. Usage in Node.js

Import and use the SDK in your Node.js application:

Find index.js file into node_modules/amtech-mail-sender directory

import { sendEmail } from './src/send-mail.js';

Configuration

Before using the SDK to send emails, you need to configure it by providing your API Key and other information about your mail such as mail_from, mail_to, subject, body, companyName etc... 


const apiKey = '__APIKEY__';
const from = 'sender@example.com';
const to = 'recipient@example.com';
const subject = 'Test Email';
const body = 'This is a test email body.';
const companyName = 'Your Company';

Replace 'YOUR_API_KEY' with the API key you received when you registered to Amtech technology account.


Usage


Sending an Email

To send an email using the Mail Sender SDK, you need to call the sendEmail method. Here’s an example of how to send an email: 

                            
import { sendEmail } from 'mail-sender-sdk';

const apiKey = 'your-sendgrid-api-key';
const from = 'sender@example.com';
const to = 'recipient@example.com';
const emailCC = 'exemple@domain.com'; // required. set the company email adresse if don't what to put here!
const emailBCC = 'exemple@domain.com'; // required. set the company email adresse if don't what to put here!
const attachment = ''; // the attachment is not supported yet. leave it blank until the update
const attachment_name = ''; // leave this blank as well
const subject = 'Test Email';
const body = 'This is a test email body.';
const companyName = 'Your Company';

sendEmail(from, to, emailCC, emailBCC, attachment, attachment_name, companyName, subject, body, apiKey)
.then(response => {
   console.log('Email sent successfully!', response);
})
.catch(error => {
   console.error('Error sending email:', error);
});

Execute the index.js file into the terminal to let it run:

node __PATH__/index.js

3. Usage in the Browser

In the browser, include the SDK via a <script> tag or use it in module format.

<script type="module" src="index.js"></script>

This is the code you will find into the index.js file:


import { sendEmail } from './path/to/index.js';

const apiKey = 'your-sendgrid-api-key';
const from = 'sender@example.com';
const to = 'recipient@example.com';
const emailCC = 'exemple@domain.com'; // required. set the company email adresse if don't what to put here!
const emailBCC = 'exemple@domain.com'; // required. set the company email adresse if don't what to put here!
const attachment = ''; // the attachment is not supported yet. leave it blank until the update
const attachment_name = ''; // leave this blank as well
const subject = 'Test Email';
const body = 'This is a test email body.';
const companyName = 'Your Company';
                            
sendEmail(from, to, emailCC, emailBCC, attachment, attachment_name, companyName, subject, body, apiKey)
    .then(response => {
    console.log('Email sent successfully!', response);
})
.catch(error => {
    console.error('Error sending email:', error);
});


API Usage


sendEmail(from, to, emailCC, emailBCC, attachment, attachment_name, companyName, subject, body, apiKey)

This function sends an email to a recipient with the specified parameters and API key.
Parameters:

  • from (String): The sender's email address.
  • to (String): The recipient's email address.
  • companyName (String): The name of the company sending the email.
  • subject (String): The subject of the email.
  • body (String): The body of the email content.
  • apiKey (String): The API key required for authentication with the email service provider (e.g., SendGrid API key).

Returns: A promise that resolves with the API response when the email is successfully sent, or rejects with an error message if the email fails to send.

Error Handling

The SDK includes built-in error handling to gracefully handle potential issues during the email sending process.


Common Errors:

    CORS Issues: When using the SDK in a browser, Cross-Origin Resource Sharing (CORS) issues might arise if the mail API server doesn't allow the origin. Make sure CORS headers are configured properly on the server. Network Errors: If the request to the mail API fails due to network issues, the SDK will reject with an appropriate error message. Invalid API Key: If an invalid or expired API key is provided, the SDK will reject with an error.

Example Error Response:


{
    "status_code": 404,
    "status": "Error",
    "success": false,
    "message": "Your API key is invalid. please create Amtech technology account to get an API key",
    "copyright": {
        "Company": "Amtech technology (Amtech-co LLC | Software)",
        "Website": "https://amtech-co.com",
        "License": "ATOSL (Amtech Technology Open Source License)"
    }
}

FAQ


  • Q1: Can I use this SDK with other email providers? Yes! This SDK is designed to work with any email service provider that allows sending emails via an HTTP API. If you use a different provider (such as Mailgun, Amazon SES, etc.), you just need to ensure that the API endpoint and required headers match your provider's specifications.

  • Q2: What if my email fails to send? If the email fails to send, the SDK will reject with an error. This could be due to various reasons, such as invalid API credentials, network issues, or server-side errors. Ensure that your API key and configuration are correct, and check for any CORS issues when using the SDK in the browser.

  • Q3: Is there a way to check if the email was successfully sent? Yes! The SDK resolves the promise with a response object, which you can inspect to confirm if the email was successfully sent. If the email fails, the error message will be returned.


Download the SDK on Github

Download the SDK through this link if you don't know how to manage the npm commands. Click here!


Conclusion

The Mail Sender SDK for JavaScript is a powerful tool to seamlessly integrate email functionality into your applications. Whether you need to send password reset emails, notifications, or newsletters, the SDK makes the process simple and effective. For further assistance, documentation, or updates, contact us through Whatsapp: +243 977 776 716 or E-mail: contact@amtech-co.com