Email Gateway Integration Guide

Email Gateway Integration Guide v1

1. Introduction

Purpose

The Email Gateway API enables seamless integration of email functionality into applications, allowing developers to send emails, manage authentication, retrieve logs, and handle webhooks efficiently. This guide provides a comprehensive overview of authentication mechanism, API endpoints, security best practices, and troubleshooting steps.

Audience

This guide is intended for developers, DevOps engineers, and product managers who need to integrate email-sending capabilities into their applications using the Email Gateway API.

API Version

1.0.0

Import the collection

View Postman Collection

2. Prerequisites

Accounts

To access the API, Enter the Access token provided by service provider (Kalp Studio)

Credentials

• Email authkey (for sending emails)

Tools

• Postman (Recommended for API testing)

• cURL (Command-line request testing)

Permissions

• Requires valid authentication credentials.

3. Authentication & Authorization

Methods

• Uses email auth key validation.

• The emailauthkey would be validated and authenticated .

4. Base URLs & Environments

Production vs. Sandbox

• Production: https://email-api.p2epl.io

5. Endpoint Reference

Email Endpoints

Method - POST

Endpoint - /v1/send/email

Description - Send an email without an attachment

Method - POST

Endpoint - /v1/send/attachemail

Description - Send an email with or without an attachment

Method - GET

Endpoint - /v1/logs

Description - Retrieve email logs

6. Error Handling

400 - Unauthorized, you do not have permission to access this service.

404 - Check your URL please

400 - Invalid Request Format

400 - Please take a moment before sending another email

500 - Internal Server Error

Example Error Response

`{ "status": "failure", "message": "Invalid Request Format", "customErrorNumber": -999999, "errorFields": [ "emailType" ] }`

7. Rate Limits & Quotas

• 5 requests per minute per email recipient.

8. API Reference

1. How to send an email -

Example Request (CURL) - Send Email without an attachment

curl --location 'https://email-api.p2epl.io/v1/send/email' \ --header 'emailauthkey: keynames123 \ --header 'Content-Type: application/json' \ --data-raw '{ "emailTo": "[email protected]", "emailFrom": "[email protected]", "subject": "FIRST MAIL", "message": "This is email from prod environment", "category": "account_related", "emailType": "account" }'

Step 1: Navigate to Email-gateway Public

Workspace in Postman

link

Email-gateway Public

Step 2: Select the “Email-gateway“ folder in the collection list.

enter image description here

Step 3: Select “v1 email” folder from the collection list.

enter image description here

Step 4: Select “POST sendemail” from the collection list.

enter image description here

Step 5: Click on the "Headers" tab and enter your emailauthkey.

enter image description here

Step 6: Click on the "Body" tab and enter all the parameter values.

enter image description here

Step 7: Click "Send"

enter image description here

Step 8: The response body will receive a success message, and an email will be sent.

enter image description here

2. How to send an email with an attachment

Example Request (CURL) - Send Email with an attachment

curl --location 'https://email-api.p2epl.io/v1/send/attachemail' \ --header 'emailauthkey: ancdef12345' \ --form 'emailTo="[email protected]"' \ --form 'emailFrom="[email protected]"' \ --form 'subject="test subject"' \ --form 'message="content test"' \ --form 'category="test"' \ --form 'emailType="transactional"' \ --form 'file=@"/C:/Users/Joe/Downloads/Holiday List 2023.pdf"' \ --form 'emailCc[0]="[email protected]"'

Step 1: Navigate to Email-gateway public.

link

Email-gateway Public

Step 2: Select the “Email-gateway“ folder in the collection list.

enter image description here

Step 3: Select “v1 email” folder from the collection list.

enter image description here

Step 4: Select “POST attachemail” from the collection list.

Send Email is the route for sending email with an attachment. The body content is in Form Data.

enter image description here

Step 5: Click on the "Headers" tab and enter your emailauthkey.

enter image description here

Step 6: Click on the "Body" tab and enter all the parameter values.

enter image description here

Step 7: Click "Send"

enter image description here

Step 8: The response body will receive a success message and an email with an attachment will be sent.

enter image description here

3. How to retrieve email logs

Example Request (CURL) - How to retrieve email logs

curl --location 'https://email-api.p2epl.io/v1/logs?pageNo=1&pageSize=10' \ --header 'emailauthkey: abcdef12345'

Step 1: Navigate to Email-gateway Public

link

Email-gateway Public

Step 2: Select "GET email logs" in “v1 email” folder from the collection list.

enter image description here

Step 3: Set the query parameters as per the requirement. "pageNo" ,"pageSize" or other parameters in the "Params" tab.

enter image description here

Step 4: Click on the "Headers" tab and enter your emailauthkey.

enter image description here

Step 5: Click "Send"

enter image description here

Step 6: The response body will receive a success message and all email logs.

enter image description here