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
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": "subhankar.roy@mai.io", "emailFrom": "subhankar.roy@p2eppl.com", "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
Step 2: Select the “Email-gateway“ folder in the collection list.
Step 3: Select “v1 email” folder from the collection list.
Step 4: Select “POST sendemail” from the collection list.
Step 5: Click on the "Headers" tab and enter your emailauthkey.
Step 6: Click on the "Body" tab and enter all the parameter values.
Step 7: Click "Send"
Step 8: The response body will receive a success message, and an email will be sent.
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="testeme@yopmail.com"' \ --form 'emailFrom="test@p2eppl.com"' \ --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]="testeme@yopmail.com"'
Step 1: Navigate to Email-gateway public.
Step 2: Select the “Email-gateway“ folder in the collection list.
Step 3: Select “v1 email” folder from the collection list.
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.
Step 5: Click on the "Headers" tab and enter your emailauthkey.
Step 6: Click on the "Body" tab and enter all the parameter values.
Step 7: Click "Send"
Step 8: The response body will receive a success message and an email with an attachment will be sent.
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
Step 2: Select "GET email logs" in “v1 email” folder from the collection list.
Step 3: Set the query parameters as per the requirement. "pageNo" ,"pageSize" or other parameters in the "Params" tab.
Step 4: Click on the "Headers" tab and enter your emailauthkey.
Step 5: Click "Send"
Step 6: The response body will receive a success message and all email logs.
