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. With a single integration, you can manage all your outbound communications without adding a separate email provider to your stack.
This guide walks you through everything you need to send your first email using the Messages API.
The Email channel is currently in Beta. During this phase, onboarding is managed by your Account Manager.
Prerequisites
Before you begin, make sure you have the following:
- A Vonage API account
- Your API key and API secret, available from the Vonage API Dashboard
- A verified sending domain — see Domain Authentication Setup below
- Beta access to the Email channel — contact your Account Manager
Email Onboarding
To get onboarded, follow these steps:
- Provide the following information to your Account Manager:
- Your Vonage API key
- The custom domain(s) from which you will send emails (for example, yourdomain.com)
- Your preferred region for domain verification: US, EU, or APAC
You can only verify a domain in one region during Beta. Choose the region closest to your users or infrastructure.
- Your Account Manager passes the information to the Product Manager, who initiates the onboarding process.
- Vonage provides a set of DNS records that you must add to your domain's DNS configuration. See Domain Authentication Setup for the full list of records and what each one does.
- Once you have updated your DNS records, confirm this with your Account Manager. DNS verification can take up to 72 hours to complete.
- Add your DNS records promptly, propagation can take up to 72 hours. If it takes longer than expected, we recommend generating new DNS records for your domain.
- When verification is complete, Vonage notifies your Account Manager, and you can start sending emails via the Messages API.
Once your domain is verified in a region, you must use the corresponding regional endpoint for all email requests. Requests sent to a different regional endpoint will fail.
| Region | Endpoint |
|---|---|
| EU | https://api-eu.nexmo.com/v1/messages/ |
| US | https://api-us.nexmo.com/v1/messages/ |
| APAC | https://api-ap.nexmo.com/v1/messages/ |
Domain Authentication Setup
Before you can send emails, you must authenticate your sending domain. Domain authentication improves email deliverability and allows mailbox providers to verify that Vonage is authorised to send emails on your behalf.
Authentication is completed by adding DNS records to your domain's DNS configuration. These records enable:
- SPF (Sender Policy Framework) — authorises Vonage's sending infrastructure to send on behalf of your domain.
- DKIM (DomainKeys Identified Mail) — cryptographically signs outgoing emails so receiving servers can verify the content has not been tampered with.
- DMARC (Domain-based Message Authentication, Reporting & Conformance) — defines the policy for handling authentication failures and provides reporting.
Major mailbox providers such as Google, Microsoft, and Yahoo rely on these mechanisms to determine whether emails should be delivered, rejected, or marked as spam.
DNS Records to Configure
Vonage provides the exact DNS record values during onboarding. The table below shows the structure and type of each record you will need to add:
| Type | Record Type | Host / Key | Value | Description |
|---|---|---|---|---|
| AUTH | CNAME | <dkim_key_1>._domainkey.<your_domain> | <dkim_value_1>.dkim.xxxx.com | DKIM Record |
| AUTH | CNAME | <dkim_key_2>._domainkey.<your_domain> | <dkim_value_2>.dkim.xxxx.com | DKIM Record |
| AUTH | CNAME | <dkim_key_3>._domainkey.<your_domain> | <dkim_value_3>.dkim.xxxx.com | DKIM Record |
| SEND | TXT | _dmarc.<your_domain> | v=DMARC1; p=none; | DMARC Policy |
| SEND | TXT | <your_domain> | v=spf1 include:.xxxx.com ~all | SPF Record |
Send Your First Email
Once your domain is verified, you are ready to send emails via the Messages API.
Create a Vonage Application
To use the Messages API, you need a Vonage Application with the Messages capability enabled. The application holds your webhook configuration and authentication credentials.
- Go to Create an Application in the Vonage Dashboard.
- Give your application a name.
- Click Generate public and private key. Your private key file downloads automatically — store it securely, as it cannot be re-downloaded.
- Under Capabilities, enable Messages.
- Set your Inbound URL and Status URL to the webhook endpoints in your application. If you do not have these yet, you can use placeholder URLs and update them later.
- Click Generate new application.
For more information, see Create a Vonage Application.
Set Your Replaceable Values
The code examples in this guide use the following variables. Replace each one with your actual values before running the examples.
| Variable | Description |
|---|---|
VONAGE_API_KEY | Your Vonage API key, found in the API Dashboard. |
VONAGE_API_SECRET | Your Vonage API secret. |
VONAGE_APPLICATION_ID | The ID of the Vonage Application. |
VONAGE_PRIVATE_KEY | The path to the private key file. |
FROM_EMAIL | Your verified sender email address (for example, support@yourdomain.com). |
TO_EMAIL | The recipient's email address. |
EMAIL_SUBJECT | The subject line of the email. |
Generate a JWT
The Messages API uses JSON Web Tokens (JWTs) for authentication. Generate a JWT using your Application ID and private key.
Send a Text Email
Use the following request to send a plain text email:
If the request is successful, you receive a response containing the message_uuid:
Send an HTML Email
To send an email with HTML content, set message_type to "html" and provide your HTML markup in the body field:
Check Delivery Status
After sending an email, Vonage sends delivery status updates to the Status URL configured in your Vonage Application. Each update is a POST request containing the message_uuid and a status field.
The key statuses for the Email channel are:
| Status | Description |
|---|---|
submitted | The email has been accepted and queued for delivery. |
delivered | The email was successfully delivered to the recipient's mailbox. |
read | The recipient opened the email. |
rejected | The email could not be delivered — check the error code for details. |
Email Pricing
Email API pricing is subscription-based and available in six tiers. Each tier includes a fixed number of emails. Once you have used the emails included in your plan, overage charges apply on a per-email basis. For current pricing details, contact your Account Manager.