Email

Overview

VoIPBIN’s Email API provides a reliable and scalable email delivery service for your applications. Whether you need to send transactional emails, notifications, or marketing communications, the Email API handles delivery while you focus on your content.

With the Email API you can:

• Send emails with HTML and plain text content

• Attach files to your emails

• Track email delivery status

• Manage mailboxes for receiving emails

• Integrate email into automated workflows

How Email Works

When you send an email, VoIPBIN processes and delivers it through email infrastructure optimized for deliverability.

Email Architecture

+----------+        +----------------+        +-------------+
| Your App |--API-->|    VoIPBIN     |--SMTP->|   Email     |
+----------+        |   Email Hub    |        |   Provider  |
                    +----------------+        +------+------+
                           |                         |
                           |                         v
                    +------+------+           +-------------+
                    |   Webhook   |           |  Recipient  |
                    |  (status)   |           |   Inbox     |
                    +-------------+           +-------------+

Key Components

• Email Hub: Processes emails, manages delivery queue, handles retries

• Email Provider: Routes emails through established email infrastructure

• Webhooks: Notify your application of delivery events

Email Lifecycle

Every email moves through states from composition to delivery.

Email States

POST /emails
      |
      v
+------------+
|  queued    |
+-----+------+
      |
      v
+------------+     delivery issue      +------------+
|  sending   |------------------------>|  bounced   |
+-----+------+                         +------------+
      |
      | accepted by server
      v
+------------+     recipient issue     +------------+
| delivered  |------------------------>|  bounced   |
+------------+                         +------------+

State Descriptions

State	What’s happening
queued	Email is in the delivery queue, waiting to be sent
sending	Email is being transmitted to the recipient’s mail server
delivered	Email was accepted by the recipient’s mail server
bounced	Email could not be delivered (invalid address, mailbox full)

Sending Emails

Send emails through the VoIPBIN API with full control over content and formatting.

Send Email via API

Your App                    VoIPBIN                    Recipient
   |                           |                           |
   | POST /emails              |                           |
   +-------------------------->|                           |
   |                           | Queue and send            |
   |                           +-------------------------->|
   |  email_id                 |                           |
   |  status: "queued"         |                           |
   |<--------------------------+                           |
   |                           |                           |
   | Webhook: delivered        |   Email in inbox          |
   |<--------------------------+-------------------------->|
   |                           |                           |

Basic Email Example:

$ curl -X POST 'https://api.voipbin.net/v1.0/emails?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "from": {
            "email": "[email protected]",
            "name": "Your Company"
        },
        "to": [
            {
                "email": "[email protected]",
                "name": "John Doe"
            }
        ],
        "subject": "Your Order Confirmation",
        "content": {
            "text": "Thank you for your order #12345.",
            "html": "<h1>Thank you!</h1><p>Your order #12345 has been confirmed.</p>"
        }
    }'

Email with Attachment:

$ curl -X POST 'https://api.voipbin.net/v1.0/emails?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "from": {
            "email": "[email protected]",
            "name": "Billing Department"
        },
        "to": [
            {
                "email": "[email protected]"
            }
        ],
        "subject": "Your Invoice",
        "content": {
            "text": "Please find your invoice attached.",
            "html": "<p>Please find your invoice attached.</p>"
        },
        "attachments": [
            {
                "filename": "invoice-12345.pdf",
                "content": "<base64-encoded-content>",
                "type": "application/pdf"
            }
        ]
    }'

Email Components

Understanding email structure helps you create effective messages.

Email Object Structure

+---------------------------------------------------------------+
|                         Email                                 |
+---------------------------------------------------------------+
| From: sender@company.com (Sender Name)                        |
+---------------------------------------------------------------+
| To: recipient@example.com                                     |
| CC: copy@example.com                                          |
| BCC: hidden@example.com                                       |
+---------------------------------------------------------------+
| Subject: Your Order Confirmation                              |
+---------------------------------------------------------------+
| Content:                                                      |
|   - Plain text version (for simple clients)                   |
|   - HTML version (for rich formatting)                        |
+---------------------------------------------------------------+
| Attachments:                                                  |
|   - invoice.pdf                                               |
|   - receipt.png                                               |
+---------------------------------------------------------------+

Email Fields

Field	Description
from	Sender email address and optional display name
to	List of recipient email addresses
cc	Carbon copy recipients (visible to all)
bcc	Blind carbon copy recipients (hidden from others)
subject	Email subject line
content.text	Plain text version of the email body
content.html	HTML version of the email body
attachments	List of file attachments

Content Best Practices

Create emails that render well and avoid spam filters.

HTML Email Structure

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body style="font-family: Arial, sans-serif; margin: 0; padding: 20px;">
    <table width="100%" cellpadding="0" cellspacing="0">
        <tr>
            <td align="center">
                <h1 style="color: #333;">Welcome!</h1>
                <p>Your email content here.</p>
            </td>
        </tr>
    </table>
</body>
</html>

Content Guidelines

Common Scenarios

Scenario 1: Order Confirmation

Send transactional emails for e-commerce.

Order placed
     |
     v
+--------------------------+
| Generate confirmation    |
| email with order details |
+------------+-------------+
             |
             v
POST /emails
Subject: "Order #12345 Confirmed"
             |
             v
Customer receives confirmation

Scenario 2: Password Reset

Send security-related emails.

User requests reset
     |
     v
+------------------------+
| Generate reset token   |
| Create reset link      |
+------------+-----------+
             |
             v
POST /emails
Subject: "Reset Your Password"
Content: Link with token
             |
             v
User receives reset email

Scenario 3: Invoice Delivery

Send emails with attachments.

Invoice generated
     |
     v
+------------------------+
| Create PDF invoice     |
| Base64 encode content  |
+------------+-----------+
             |
             v
POST /emails
Attachment: invoice.pdf
             |
             v
Customer receives invoice

Scenario 4: Marketing Newsletter

Send bulk marketing emails.

+------------------------------------------+
| For each subscriber:                     |
|                                          |
| POST /emails                             |
| {                                        |
|   "to": [{"email": subscriber}],         |
|   "subject": "Weekly Newsletter",        |
|   "content": {...}                       |
| }                                        |
+------------------------------------------+
                  |
                  v
Monitor delivery status via webhooks

Best Practices

1. Sender Reputation

• Use a consistent “from” address for each email type

• Authenticate your domain (SPF, DKIM, DMARC)

• Maintain low bounce and complaint rates

2. Content Quality

• Always include both HTML and plain text versions

• Keep subject lines concise and relevant

• Avoid spam trigger words and excessive punctuation

3. List Management

• Honor unsubscribe requests immediately

• Remove bounced addresses from your lists

• Segment your audience for relevant content

4. Deliverability

• Warm up new sending domains gradually

• Monitor delivery metrics and adjust as needed

• Use dedicated IP addresses for high-volume sending

Troubleshooting

Delivery Issues

Symptom	Solution
Email bounced	Check recipient address validity; verify mailbox exists
Marked as spam	Review content for spam triggers; check sender reputation
Delayed delivery	Check sending rate; verify no throttling

Rendering Issues

Symptom	Solution
HTML not displaying	Use inline CSS; avoid external resources
Images not showing	Use absolute URLs; include alt text
Layout broken	Use table-based layouts; test across clients

Attachment Issues

Symptom	Solution
Attachment blocked	Avoid executable files; use common formats
File too large	Compress files; use file hosting links

Related Documentation

• Message Overview - SMS/MMS messaging

• Conversation Overview - Unified multi-channel messaging

• Webhook Overview - Webhook configuration

Email

Email

{
    "id": "<uuid>",
    "customer_id": "<uuid>",
    "source": {
        ...
    },
    "destinations": [
        {
            ...
        },
        ...
    ],
    "status": "<string>",
    "subject": "<string>",
    "content": "<string>",
    "attachments": [
        {
            ...
        },
        ...
    ],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
},

• id: Email’s ID.

• customer_id: Customer’s ID.

• source: Source address info. See detail here.

• destinations: List of destination addresses info. See detail here.

• status: Email’s deliverence status. See detail here.

• subject: Email’s subject.

• content: Email’s content.

• attachments: List of attachments. See detail here.

Example

{
    "id": "1f25e6c9-6709-44d1-b93e-a5f1c5f80411",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "source": {
        "type": "email",
        "target": "[email protected]",
        "target_name": "voipbin service",
        "name": "",
        "detail": ""
    },
    "destinations": [
        {
            "type": "email",
            "target": "[email protected]",
            "target_name": "",
            "name": "",
            "detail": ""
        }
    ],
    "status": "delivered",
    "subject": "test email 7",
    "content": "test email from voipbin.",
    "attachments": [],
    "tm_create": "2025-03-14 19:04:01.160250",
    "tm_update": "2025-03-14 19:04:11.509512",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Status

Email’s status.

Status	Description
“”	None
initiated	The email has been initiated.
processed	The email has been received is being processed.
delivered	The email has been successfully delivered to the recipient’s inbox (or spam folder).

Attachment

Attachment

{
    "reference_type": "<string>",
    "reference_id": "<uuid>"
}

• reference_type: Attachment’s reference type.

• reference_id: Attachment’s reference id.

Type

Attachment’s type.

Type	Description
“”	None
recording	Recording.

Tutorial

Get list of emails

Example

$ curl --location 'https://api.voipbin.net/v1.0/emails?accesskey=your_accesskey'

{
    "result": [
        {
            "id": "1f25e6c9-6709-44d1-b93e-a5f1c5f80411",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "source": {
                "type": "email",
                "target": "[email protected]",
                "target_name": "voipbin service",
                "name": "",
                "detail": ""
            },
            "destinations": [
                {
                    "type": "email",
                    "target": "[email protected]",
                    "target_name": "",
                    "name": "",
                    "detail": ""
                }
            ],
            "status": "delivered",
            "subject": "test email 7",
            "content": "test email from voipbin.",
            "attachments": [],
            "tm_create": "2025-03-14 19:04:01.160250",
            "tm_update": "2025-03-14 19:04:11.509512",
            "tm_delete": "9999-01-01 00:00:00.000000"
        },
        ...
    ],
    "next_page_token": "2025-03-14 18:04:41.998152"
}