Getting Started with Email

The Vonage Messages API supports Email as a channel, enabling you to send transactional emails using the same API contract you already use for other messaging channels.

Prerequisites

Before you begin, make sure you have:

• A Vonage API account
• Your API key and API secret from the Vonage API Dashboard
• A sending domain that you can manage in DNS
• Beta access to the Email channel

Email Onboarding

To get onboarded with the Email API:

1. Provide the following information to your Account Manager:
   • Your Vonage API key
   • The custom domain(s) you plan to use for sending (for example, yourdomain.com)
   • Your preferred region for domain verification (US, EU, or APAC)
2. Your Account Manager passes this information to the internal team to initiate onboarding.
3. Vonage provides the DNS records that you need to add to your domain. See Domain Authentication Setup.
4. After updating DNS, confirm completion with your Account Manager. DNS verification can take up to 72 hours.
5. Add DNS records promptly. If propagation takes longer than expected, raise a support ticket or contact your Account Manager.
6. Once verification completes successfully, Vonage notifies your Account Manager and you can start sending email with the Messages API.

Domain Authentication Setup

Before you can send emails, you must authenticate your sending domain. Domain authentication improves deliverability and allows mailbox providers to verify that Vonage is authorized to send on your behalf.

Authentication is completed by adding DNS records to your domain. These records enable:

• SPF (Sender Policy Framework) to authorize Vonage sending infrastructure.
• DKIM (DomainKeys Identified Mail) to cryptographically sign outgoing email content.
• DMARC (Domain-based Message Authentication, Reporting and Conformance) to define policy and reporting for authentication failures.

Major mailbox providers, including Google, Microsoft, and Yahoo, rely on these standards when deciding whether to deliver, reject, or filter messages.

For more context, see Factors affecting your email deliverability.

DNS Records to Configure

Vonage provides the exact values during onboarding. The table below shows the expected record structure:

Authentication Best Practices

• Configure all DKIM records provided by Vonage for each sending domain.
• Start with DMARC p=none during monitoring, then apply stricter policies when ready.
• Add Vonage to your SPF record using include:msg.vonage.com.
• If you already have an SPF record, append the Vonage include instead of replacing existing entries.

Example:

• Existing SPF: v=spf1 include:example.com ~all
• Updated SPF: v=spf1 include:example.com include:msg.vonage.com ~all

Advanced DNS Options

• Click and open tracking DNS: Vonage can provide additional CNAME records for tracking configuration.
• Custom mail from / return-path: Vonage supports custom return-path configuration and may provide additional MX and TXT records.

Ask your Account Manager if you need these advanced options during onboarding.

Send Your First Email

Once your domain is verified, you are ready to send email messages with the Messages API.

Create a Vonage Application (Optional)

To use the Messages API, you need a Vonage Application with the Messages capability enabled.

1. Go to Create an Application in the Vonage Dashboard.
2. Enter an application name.
3. Click Generate public and private key and store the private key securely.
4. Under Capabilities, enable Messages.
5. Set your Inbound URL and Status URL webhooks.
6. Click Generate new application.

For more information, see Create a Vonage Application.

Set Your Replaceable Values

Use the following variables in examples and replace them with your own values:

Generate a JWT

The Messages API uses JWT authentication. Generate a JWT using your Application ID and private key before calling the API.

Send a Text Email

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "text",
   "text": "Email body text",
   "email": {
      "subject": "Email subject"
   }
}

If successful, the API response contains message_uuid:

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Send an HTML Email

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "html",
   "html": {
      "body": "<p>Email body html</p>"
   },
   "email": {
      "subject": "Email subject"
   }
}

Email Size Limits

The email body supports up to 100 KB per API request. If the body exceeds this limit, the request returns an error.

The Messages API also enforces a network-level payload limit of 200 KB.

Check Delivery Status

After sending an email, Vonage sends message status updates to your configured Status URL.

Factors Affecting Your Email Deliverability

Email deliverability is the ability of an email message to reach the recipient inbox.

Delivery and deliverability are different:

• Delivery means the receiving mail server accepted the message.
• Deliverability means the message reaches the inbox instead of spam or rejection.

Shared Responsibility Model

Email deliverability is a shared responsibility between Vonage and the customer.

1. Domain Authentication

Domain authentication is one of the most important deliverability factors.

• DKIM signs message content.
• DMARC defines handling policy for authentication failures.
• SPF authorizes approved senders.

These standards help mailbox providers verify sender identity and message integrity.

2. Sender Reputation

Mailbox providers continuously evaluate domain and IP reputation.

Poor reputation can lead to:

• Spam-folder placement
• Temporary throttling
• Message rejection
• Lower inbox placement

Reputation is influenced by spam complaints, bounce rates, sending consistency, user engagement, and message quality.

Best practices:

• Send only to recipients who expect your messages.
• Avoid sudden spikes in send volume.
• Remove inactive recipients regularly.
• Monitor bounce and complaint rates.

3. Email Content Quality

Mailbox providers also evaluate message content quality.

Broken links, suspicious attachments, excessive image-only content, or oversized payloads can negatively impact deliverability.

Best practices:

• Use trusted domains in links.
• Keep message content clear, relevant, and well-structured.
• Maintain a healthy text-to-image balance.
• Validate attachments and keep payload size within supported limits.

4. Recipient Engagement

Mailbox providers use recipient engagement signals for inbox placement.

Positive signals include opens, clicks, replies, and moving messages from spam to inbox. Negative signals include complaints, immediate deletion, and long-term inactivity.

Higher engagement generally improves sender reputation.

5. Bounce Management

Hard and soft bounces affect sender reputation differently.

• Hard bounce: permanent failure (for example, invalid address or non-existent recipient).
• Soft bounce: temporary failure (for example, mailbox full or temporary server issue).

Vonage automatically processes bounce events and manages suppression behavior to reduce repeated delivery attempts to permanently undeliverable recipients.

6. Spam Complaints

Spam complaints are among the strongest negative trust signals used by mailbox providers.

High complaint rates can cause:

• Lower inbox placement
• Temporary blocks
• Permanent reputation damage

Best practices:

• Send only to users who have opted in.
• Clearly identify your organization.
• Make unsubscribe easy and visible.
• Honor unsubscribe requests promptly.

Vonage processes spam events and suppresses re-sending to affected recipients.

7. List Quality

Outdated, invalid, or purchased recipient lists significantly reduce deliverability.

Poor list quality increases:

• Hard bounces
• Spam complaints
• Unsubscribes

Best practices:

• Collect addresses through valid opt-in flows.
• Remove invalid recipients quickly.
• Regularly clean inactive recipients.
• Never purchase email lists.

Email Pricing

Email API pricing is subscription-based and available in multiple tiers. Each tier includes a fixed number of emails, with overage charges applied per additional email.

For current pricing details, contact your Account Manager.

Further Information

• Understanding Email Messaging
• Messages API Reference