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.

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:

1. 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

2. Your Account Manager passes the information to the Product Manager, who initiates the onboarding process.
3. 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.
4. Once you have updated your DNS records, confirm this with your Account Manager. DNS verification can take up to 72 hours to complete.
5. 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.
6. When verification is complete, Vonage notifies your Account Manager, and you can start sending emails via the Messages API.

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:

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.

1. Go to Create an Application in the Vonage Dashboard.
2. Give your application a name.
3. Click Generate public and private key. Your private key file downloads automatically — store it securely, as it cannot be re-downloaded.
4. Under Capabilities, enable Messages.
5. 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.
6. 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.

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:

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

If the request is successful, you receive a response containing the message_uuid:

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

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:

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

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:

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.

Further Information

• Understanding Email Messaging
• Messages API Reference