BillionMail API Email Sending Function Guide

Function Overview

BillionMail API's email sending function provides a complete email delivery solution, supporting the following core features:

• ✉️ Template-based email sending

• 👤 Customizable sender

• 📊 Comprehensive data tracking (Opened rate/Clicked rate/Bounced rate)

• 🔄 Unsubscription management

• 📈 Detailed sending statistics

API Key Management

Create an API Key

Sending API --> Create API

Click "Create API" and fill in relevant information (API name, email template, sender, subject, IP whitelist, etc.). The system will automatically generate a unique API Key.

• Supports independent IP whitelist configuration for each API to enhance security

Email Sending API

Send a Single Email

Request Information:

• Endpoint: /api/batch_mail/api/send

• Method: POST

• Authentication: Required

Request Headers:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Request Body:

{
    "recipient": "[email protected]",  
    "addresser": "[email protected]",
    "attribs": {
        "username": "Jesse",
        "order_id": "20240501"
    }
}

Request Parameter Description:

Parameter	Type	Required	Description
recipient	string	Yes	Recipient's email address
addresser	string	No	Custom sender's email address
attribs	map[string]string	No	Custom attributes for template variable replacement

Note: If the addresser parameter is not passed, the default sender email will be used.

The attribs field can be used for personalization of email template variables. In the email template, use

{{.API.attribute name}}

For example

{{.API.username}}
{{.API.order_id}}

Response Example:

{
  "success": true,
  "code": 0,
  "msg": "Email sent successfully",
  "data": null
}

Usage Examples

CURL Example

# Send an email
curl -k -X POST 'https://your-domain.com/api/batch_mail/api/send' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "recipient": "[email protected]",
    "attribs": {
        "username": "Jesse",
        "order_id": "20240501"
    }
    
}'

Python Example

import requests

def send_email(api_key, recipient, attribs):
    url = 'https://your-domain.com/api/batch_mail/api/send'
    headers = {
        'X-API-Key': api_key
    }
    data = {
        'recipient': recipient,
        'attribs': attribs 
        }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Batch Sending API

Endpoint Information:

• Endpoint: /api/batch_mail/api/batch_send
• Method: POST
• Authentication: Required

Request Headers:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Request Body Example:

{
    "recipients": [
        "[email protected]",
        "[email protected]"
    ],
    "addresser": "[email protected]",
    "attribs": {
        "promo_code": "VIP2024",
        "username": "Dear User"
    }
}

Parameter Description:

Parameter	Type	Required	Description
recipients	string[]	Yes	Array of recipient email addresses
addresser	string	No	Custom sender email address
attribs	map[string]string	No	Custom attributes, shared by all recipients

Note: For batch sending, variables in attribs will be applied to template rendering for all recipients.

Response Example:

{
  "success": true,
  "code": 0,
  "msg": "Batch email send request accepted, 2 emails queued",
  "data": null
}

---

Template Variable Personalization Instructions

• For batch sending, all recipients share the same set of attribs.
• For single sending, different attribs can be passed for each recipient individually.
• The email template can use the following variables, whose values are passed by attribs.

{{.API.username}}
{{.API.promo_code}}

---

Usage Examples

Batch Sending CURL Example

curl -X POST 'https://your-domain.com/api/batch_mail/api/batch_send' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "recipients": ["[email protected]", "[email protected]"],
    "addresser": "[email protected]",
    "attribs": {
        "promo_code": "VIP2024",
        "username": "Dear User"
    }
}'

Batch Sending Python Example

import requests

def batch_send_email(api_key, recipients, attribs):
    url = 'https://your-domain.com/api/batch_mail/api/batch_send'
    headers = {
        'X-API-Key': api_key
    }
    data = {
        'recipients': recipients,
        'attribs': attribs
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Error Code Explanation

Error Code	Description	Solution
1001	Invalid API key	Check if the API key is correct
1002	IP not allowed	Check if the IP whitelist is set
1003	Invalid recipient	Check the email address format
1004	Template does not exist	Check the template ID
1005	Sending failed	View detailed error logs

Feature Descriptions

IP Whitelist Function

• Each API can be individually configured with an IP whitelist, allowing only specified IPs to call the API.

• If no whitelist is set, all IPs can access the API.

• Whitelists can be configured during API creation and updates, and can be adjusted at any time later.

• Calls from non-whitelist IPs will return error code 1002.

Email Tracking Function

• Open Tracking

  • Automatically records the number of email opens

  • Counts the number of unique open users

  • Provides data on open time distribution

• Link Tracking

  • Tracks clicks on links in emails

  • Records clicking users and times

  • Analyzes link click popularity

• Data Statistics

  • Updates statistical data in real-time

  • Provides multi-dimensional analysis

Unsubscription Management (Optional)

• Unsubscription Link

  • Automatically adds an unsubscription link at the bottom of emails

  • Supports one-click unsubscription

  • Automatically updates unsubscription status

• Unsubscription List Management

  • Maintains a global unsubscription list

Sending Statistics

Provides statistical data in the following dimensions:

• Total number of sent emails

• Delivery rate

• Open rate

• Click-through rate

• Bounce rate

• Unsubscription rate

Best Practices

Security Recommendations

1. API Key Management

   • Properly store API keys

   • Regularly replace API keys

   • Avoid key leakage

2. Access Control

   • Use HTTPS for API calls

   • Set up IP whitelists

   • Monitor abnormal access

Sending Optimization

1. Sending Strategy

   • Reasonably control sending frequency

   • Avoid intensive sending

   • Pay attention to sending statistics

2. Address Management

   • Regularly clean up invalid addresses

   • Promptly handle bounced emails

   • Maintain a blacklist

Content Optimization

1. Template Management

   • Use variables to achieve personalization

   • Keep templates concise

   • Update content regularly

2. Performance Optimization

   • Conduct A/B testing

   • Analyze statistical data

   • Optimize sending time

FAQs

1. Sending Issues

Q: How to handle emails that failed to send?
A: The system automatically records failed emails. You can view the reasons for failure through the API management list in the dashboard.

2. Statistical Issues

Q: How to improve the delivery rate?
A: Maintain a good sending record, avoid sending spam, and regularly clean up invalid addresses.

3. Functional Issues

Q: How to view sending statistics?
A: You can do so through the API list in the dashboard.

4. Technical Issues

Q: Does it support batch sending?
A: Currently, the API only supports sending single emails. For batch sending, please use the task function.

5. Other Issues

Q: How to handle unsubscription requests?
A: The system automatically processes unsubscription requests and maintains the unsubscription list.