CPaaS Guide
API Guide
BlogLogin

Implement Encryption

Learn how to use encryption to protect sensitive data when calling the Send Email API.

Overview

When sending emails through the Send Email API, it is important to protect sensitive information like personal details. Read this document to know how to use AES-256 GCM encryption to secure your payload. Generate API keys, encrypt your data, and include the right headers to make a secure API request.

Prerequisites

Before you begin, ensure the following:

  • Python 3 is installed.
  • You have access to your Netcore API key.
  • Install the required pycryptodome and requests libraries given below:
pip install pycryptodome requests

How Encryption Works

The Send Email API uses AES-256 GCM for encryption. This algorithm protects both the privacy and integrity of your data.

Each request involves:

  1. Generating a 256-bit AES key (32 bytes)
  2. Generating a 12-byte Initialization Vector (IV)
  3. Encrypting your JSON payload
  4. Base64 encoding the encrypted data
  5. Sending the AES key and IV in the request headers

API Endpoint

POST https://emailapi.netcorecloud.net/v6/mail/send

Required Headers

Refer to the table below for the mandatory headers to implement the encryption payload.

HeaderDescription
Content-Typeapplication/json
AuthorizationBearer <YOUR_API_KEY>
X-Encryption1
X-Encryption-Version2
X-AES-KEYBase64-encoded AES key
X-AES-IVBase64-encoded 12-byte Initialization Vector

Step-by-Step Example

Refer to the given steps below and use the Python script to securely send an encrypted email payload using the Send Email API.

  1. Import Libraries for encryption and HTTP requests.

  2. Define encrypt_payload() Function

  3. Add your API key and the email API endpoint URL.

  4. Create Email data (to, from, subject, content) in JSON format.

  5. Encrypts the JSON payload using the key.

  6. Set HTTP headers and the encoded AES key and IV.

  7. Send the Encrypted Request

📘

Note

Users can insert their API key and then send the encrypted payload in a secure API request.

Here’s a Python example that encrypts your payload and sends the API request.

import base64
import json
import requests
from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes

def encrypt_payload(data_bytes, key):
    iv = get_random_bytes(12)
    cipher = AES.new(key, AES.MODE_GCM, nonce=iv)
    ciphertext, tag = cipher.encrypt_and_digest(data_bytes)
    return iv, ciphertext + tag

def main():
    # Step 1: Set up API key and endpoint
    api_key = "YOUR_API_KEY"
    url = "https://emailapi.netcorecloud.net/v6/mail/send"

    # Step 2: Define JSON payload
    data = {
        "personalizations": [{
            "to": [{"email": "[email protected]", "name": "John Doe"}]
        }],
        "from": {"email": "[email protected]", "name": "Your Sender Name"},
        "subject": "Encrypted Test Email via Python",
        "content": [{"type": "html", "value": "This is a test email with an encrypted payload."}]
    }

    # Step 3: Encrypt payload
    aes_key = get_random_bytes(32)
    iv, encrypted_blob = encrypt_payload(json.dumps(data).encode('utf-8'), aes_key)

    # Step 4: Base64 encode data
    base64_key = base64.b64encode(aes_key).decode('utf-8')
    base64_iv = base64.b64encode(iv).decode('utf-8')
    final_payload = base64.b64encode(encrypted_blob).decode('utf-8')

    # Step 5: Send API request
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {api_key}',
        'X-Encryption': '1',
        'X-Encryption-Version': '2',
        'X-AES-KEY': base64_key,
        'X-AES-IV': base64_iv
    }

    response = requests.post(url, headers=headers, data=final_payload)
    print(f"Status: {response.status_code}")
    try:
        print(json.dumps(response.json(), indent=2))
    except json.JSONDecodeError:
        print(response.text)

if __name__ == "__main__":
    main()

Sample Success Response

{
  "data": {
    "message_id": "53ddac2a897fac80b16530d3c5a4ba93"
  },
  "message": "OK",
  "status": "success"
}