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

Email Onboarding

Complete domain onboarding directly in the Vonage Customer Dashboard:

1. Sign in. Log in to the Vonage Customer Dashboard.
2. Open Domain Authentication. Go to Messages > Email > Domain Authentication.
3. Request Email access. Submit a request in the Dashboard and include the API key you plan to use. If you use a subaccount API key, provide both the master API key and the subaccount API key. Vonage will notify you when the request has been processed and the domain authentication option is available.
4. Add your sending domain. Select Authenticate your domain, enter the domain, and choose the region closest to your users or infrastructure: EU, US, or APAC. A domain can be verified in only one region.
5. Copy the DNS records. The Dashboard generates the required DNS records. Copy each value exactly as shown.
6. Update your DNS settings. Add the records through your domain provider. DNS propagation can take up to 72 hours.
7. Confirm verification. Return to the Dashboard and monitor the status. When the status changes to Verified, the domain is ready for use.
8. Link the domain to an application. Link the verified domain to a Vonage Application by following the next section.

Link Your Domain to a Vonage Application

After your domain is verified, link it to a Vonage Application so that inbound email and webhook events are routed correctly.

Linking the domain enables:

• Routing inbound email to your application's webhook.
• Configuring application-level Inbound and Status URLs.
• Using secure JWT authentication scoped to the application.

To link a verified domain:

1. Open Applications. Sign in to the Vonage Customer Dashboard and go to Applications.
2. Select the application. Open the Vonage Application you want to use with the verified domain.
3. Enable Messages. Confirm that the Messages capability is enabled for the application.
4. Link the domain. Select Link your domain, choose the verified domain, and confirm the link.
5. Configure webhooks. Set the application's Inbound URL and Status URL.
6. Verify the setup. Confirm that the domain appears as linked and that the webhook URLs are correct.

Domain-linking rule: Multiple domains can be linked to one application, but each domain can be linked to only one application.

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.

You can choose the advanced DNS options via customer dashboard.

Send Your First Email

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

Create a Vonage Application

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.

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.

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.

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.

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.

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.

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.

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, see the Email API Pricing page or contact your Account Manager.

Further Information

• Understanding Email Messaging
• Understanding Inbound Email
• Messages API Reference