The GoHighLevel V2 Email API is the updated programmatic interface for sending transactional and marketing emails through the GHL infrastructure. While most GHL users send emails through the platform’s native campaign builder or automation workflows, the V2 Email API exists for developers, technical agencies, and businesses that need to integrate GHL email sending into custom applications, external systems, or advanced automation architectures that go beyond the no-code workflow builder.
The V2 designation indicates this is the second generation of GHL’s email API — rebuilt with improved authentication, better deliverability controls, richer parameter support, and enhanced error handling compared to the original V1 API. For teams that were using V1, the migration to V2 is recommended both for reliability and to access new capabilities that V1 does not support.
Explore Premium Courses Master AI, Data Engineering & Business AutomationLearn more →
Practically, the V2 Email API allows you to send an email to any contact in your GHL sub-account programmatically — triggering from code, webhooks, external databases, custom applications, or any system that can make an HTTPS request. The email sends through GHL’s email infrastructure, which means your deliverability, unsubscribe management, and email tracking all flow through GHL — keeping everything in one system while still giving you programmatic control.
When Should You Use the V2 Email API?
The GHL workflow builder handles the majority of email automation needs without requiring API access. The V2 Email API becomes relevant in specific scenarios:
If you have a custom web application, membership portal, or SaaS product that needs to trigger emails through GHL, the V2 API is the connection point. For example: a custom client portal where user actions (completing a form, reaching a milestone, making a payment) need to trigger personalized emails managed in GHL.
External System Triggers
When your email triggers originate from systems that cannot connect to GHL via native integrations or Zapier — legacy CRMs, proprietary databases, custom ERPs — the V2 API provides a universal HTTP interface for sending emails regardless of the source system.
Dynamic Email Content at Send Time
The V2 API supports passing custom variables at the time of the API call, allowing the email content to be dynamically personalized with data that is only available at send time — data from external databases, real-time calculations, or session-specific information that cannot be stored in GHL contact fields in advance.
High-Volume Transactional Email
For applications sending high volumes of transactional emails (order confirmations, password resets, delivery notifications), the V2 API provides the programmatic control and throughput management needed for reliable large-scale sending through the GHL infrastructure.
Developer and Agency Custom Builds
Technical agencies building white-label solutions on top of GHL often use the V2 API to integrate email sending into custom client dashboards, reporting tools, or automated notification systems they build for their clients.
V2 Email API vs. V1: What Changed
If your agency or development team previously used the GHL V1 Email API, here are the key differences in V2 to be aware of:
Authentication: V2 uses API key authentication with the GHL V2 API key format. V1 used an older authentication method that is being deprecated. All new integrations should use V2 authentication.
Endpoint structure: V2 endpoints follow a cleaner RESTful structure under the /conversations/messages namespace, aligning with GHL’s unified conversations API.
Contact handling: V2 requires contacts to exist in GHL before sending (identified by contact ID or email address). V1 allowed some ad hoc sending; V2 enforces the contact-centric model for better tracking and compliance.
Template support: V2 has richer support for GHL email templates, allowing you to reference a template by ID and pass variable values at send time. V1 required more raw HTML in the API call itself.
Error responses: V2 returns structured JSON error responses with specific error codes, making debugging and retry logic significantly easier to implement.
Rate limits: V2 has clearly documented rate limits (requests per minute per sub-account) compared to the softer limits in V1. Plan your send volume accordingly.
Getting Started: Prerequisites
Before making your first V2 Email API call, ensure the following are in place:
GHL V2 API Key: Generate your API key from Agency Settings → Integrations → API Keys. You need a sub-account-level API key for sending emails on behalf of a specific sub-account. Agency-level keys have different scopes.
Email sending domain configured: The sub-account must have a sending domain set up and verified (DKIM, SPF records). Emails sent via the API use the same sending infrastructure as the dashboard — unverified domains will have deliverability issues.
Contact must exist in GHL: The recipient must be a contact in the sub-account. If they don’t exist yet, create them via the Contacts API before sending the email.
Email template or raw HTML: Decide whether you are sending via a GHL-created email template (referenced by template ID) or passing raw HTML content in the API call.
V2 Email API Endpoint Reference
The primary endpoint for sending an email via V2 is:
POST https://services.leadconnectorhq.com/conversations/messages/outbound
Authorization: Bearer {YOUR_V2_API_KEY}
Content-Type: application/json
Version: 2021-04-15
Required Request Body Parameters
type: Set to "Email" to specify email as the channel.
contactId: The GHL contact ID of the recipient. Find this in the contact’s record URL or via the Contacts API.
emailFrom: The sender email address (must be a verified sending address for the sub-account).
emailSubject: The email subject line.
emailBody: The email body HTML. Use this for raw HTML content. If using a template, use templateId instead.
Optional Parameters
emailTo: Override the recipient email (defaults to the contact’s primary email).
emailCc: Array of CC email addresses.
emailBcc: Array of BCC email addresses.
emailReplyTo: Reply-to address (useful for routing replies to a support inbox).
templateId: GHL email template ID. When used, replaces emailBody.
customData: Key-value object of custom variables to inject into the template at send time.
attachments: Array of attachment objects with file URLs.
scheduledTimestamp: Unix timestamp for scheduled sending.
The customData values automatically replace matching {{variable}} placeholders in the GHL template, enabling dynamic personalization at send time without modifying the template itself.
Handling API Responses
A successful send returns HTTP 200 with a response body containing the message ID:
401 Unauthorized: Invalid or expired API key. Regenerate your key in GHL Agency Settings.
404 Not Found: Contact ID does not exist in the sub-account. Create the contact first or verify the ID.
422 Unprocessable Entity: Missing required parameters or invalid values. Check the error detail in the response body for specifics.
429 Too Many Requests: Rate limit hit. Implement exponential backoff and retry logic.
Building a Reliable Email Integration: Best Practices
Always Check Contact Existence First
Before calling the send endpoint, verify the contact exists using the Contacts API search endpoint. If they don’t exist, create them first. This prevents 404 errors and ensures all emails are tracked against a contact record in GHL.
Implement Retry Logic with Backoff
Network failures and temporary API issues are inevitable in any integration. Build retry logic that waits progressively longer between attempts (1s, 2s, 4s, 8s) and caps at 3-5 retries. Log failures for manual review rather than silently dropping emails.
Use Templates for Branded Emails
Build your email designs in GHL’s template editor and reference them by template ID in the API. This decouples your email design from your code — your marketing team can update the template in GHL without requiring a code deployment. Only use raw emailBody HTML for truly dynamic content that cannot be templated.
Respect Rate Limits
GHL V2 API enforces rate limits per sub-account. For bulk sending, implement a queue with controlled throughput rather than firing all API calls simultaneously. A simple delay-between-requests approach works for moderate volumes; for high-volume use cases, implement a proper job queue (Redis Bull, AWS SQS, etc.).
Log All Sends
Store the returned messageId and conversationId in your application database for every successful send. This gives you a reference point for debugging, tracking opens/clicks via the GHL conversations API, and reconciling delivery status.
Monitor Deliverability Separately
The V2 API confirms the message was queued, not necessarily delivered. Monitor bounce rates, spam complaints, and open rates in the GHL Email Statistics dashboard. If deliverability drops, investigate your sending domain configuration before increasing send volume.
V2 Email API for Agency Automation Architecture
For agencies building sophisticated client automation systems, the V2 Email API is one piece of a larger architecture. A common pattern:
Trigger source: Client’s external app, payment processor, or e-commerce platform fires a webhook when an event occurs (purchase, signup, cancellation, etc.).
Middleware: A lightweight Node.js or Python function (hosted on Vercel, AWS Lambda, or similar) receives the webhook, enriches the data if needed, looks up or creates the GHL contact, and calls the V2 Email API.
GHL V2 API: Sends the email through the client’s sub-account using a branded template, with dynamic variables passed at send time.
Tracking: Open and click events tracked in GHL conversations, feeding into the contact’s engagement score and triggering follow-up workflows if needed.
This architecture gives you the reliability and scale of a custom application with the deliverability management, template system, and contact tracking of GHL — without duplicating infrastructure or managing two separate email systems.
For agencies offering custom development as part of their GHL retainer, the V2 Email API is a key tool for building integrations that justify premium pricing. Clients who need their custom app connected to their GHL email system — with proper tracking, template management, and compliance handling — are willing to pay for that integration. The V2 API makes it technically straightforward to deliver.
⚡ Quick Summary
The GoHighLevel V2 Email API is not for everyone — but when your email triggers live outside GHL's workflow builder, it is the only reliable path. Use a sub-account API key, include the Version header, ensure contacts exist before sending, and use templateId with customData for dynamic personalization. V2's structured errors and conversation-thread integration make it significantly more production-ready than V1.
🎯 Key Takeaways
✔The Version: 2021-04-15 header is required on every V2 API request u2014 missing it causes authentication failures that look unrelated to the actual problem
✔Use sub-account-level API keys, not agency-level keys, for email sends u2014 the wrong key scope is the second most common cause of auth errors
✔Contacts must exist in GHL before you can send via the V2 API u2014 build a contact creation step using the Contacts API for any integration processing new records
✔templateId plus customData is the right pattern for production systems u2014 design templates in GHL's visual editor and pass dynamic values at send time, keeping content editable without code changes
✔Log the messageId from every successful API response alongside the contactId and timestamp u2014 this is how you trace missing emails in client escalations
✔Emails sent via the V2 API appear in the contact's full conversation thread, keeping communication history unified for support and account management teams
✔Implement exponential backoff on 429 rate limit responses and add 50-100ms delays in batch send loops to stay within the per-sub-account rate limits
🔍 In-Depth Guide
Getting API Key Authentication Right Before You Write Any Code
The most common mistake I see agencies make when starting with the V2 Email API is using the wrong key scope. GHL has agency-level API keys and sub-account-level API keys. For sending emails, you need a sub-account key u2014 one that is scoped specifically to the sub-account where the recipient contact lives. Agency-level keys have different permissions and will not authorize email sends in the way most developers expect. Go to Agency Settings u2192 Integrations u2192 API Keys, select the sub-account, and generate from there.nnOnce you have the key, your request headers need three things: <code>Authorization: Bearer {key}</code>, <code>Content-Type: application/json</code>, and <code>Version: 2021-04-15</code>. That last header is non-negotiable. I have seen developers spend hours on authentication errors that came down to a missing Version header. GHL's API gateway uses this header to route requests to the correct API version u2014 without it, the request fails with a misleading 401 or 400 response.nnIf you are building a multi-sub-account system u2014 which is common for agencies managing multiple client accounts u2014 you will need to handle key storage per sub-account. Never hardcode keys in source code. Use environment variables or a secrets manager, and build your key retrieval logic to map contact IDs to the correct sub-account key before making any API call.
Dynamic Email Personalization with templateId and customData
One pattern I use repeatedly with clients building custom systems is the template plus customData approach. Here is how it works in practice: a Dubai real estate agency I work with sends lease renewal notices from a property management system. The email template lives in GHL u2014 styled, branded, approved by their compliance team. The external system does not touch the template content at all. Instead, it passes four customData values at send time: tenant name, property address, renewal date, and new rent amount.nnIn GHL's template editor, those four values are referenced as <code>{{tenant_name}}</code>, <code>{{property_address}}</code>, and so on. When the API call fires, GHL substitutes the placeholders with the real values from customData before sending. The result is a properly personalized email that looks identical to what a human would have sent from the dashboard u2014 because it uses the same template infrastructure.nnThis matters operationally because the marketing team can update template design, adjust copy, or tweak the call-to-action without involving a developer. The code integration stays stable while the content stays flexible. If your external system is sending raw HTML in every API call instead, you are coupling content decisions to your codebase unnecessarily. Move templates into GHL and reference them by ID.
Error Handling and Rate Limits for Production Email Systems
A production email integration needs to handle failures gracefully u2014 not just log them and move on. The GHL V2 API returns structured JSON error responses with specific codes, which makes building retry logic much cleaner than V1. The errors you will encounter most often: 400 (malformed request u2014 usually a missing required field or invalid contactId), 401 (authentication failure u2014 wrong key or missing Version header), 404 (contact not found in the sub-account), and 429 (rate limit exceeded).nnFor 429 errors, GHL enforces rate limits per sub-account. The documented limit is around 100 requests per minute per sub-account, though this can vary by plan. If you are doing high-volume transactional sends, implement exponential backoff on 429 responses rather than hammering the endpoint. For batch operations, add a small delay between sends u2014 50 to 100 milliseconds u2014 to stay well below the threshold.nnAlways log the <code>messageId</code> from successful responses. GHL uses this ID across its internal systems, and if a client reports a missing email, that ID is how you trace it. Store it alongside the contact ID and timestamp in your own database. That one habit has saved me hours of back-and-forth with support on client escalations. Today's action: add messageId logging to any existing GHL email integration you have running.
Most GoHighLevel users never need to touch the API. The workflow builder handles 90% of email automation without writing a single line of code. But the moment a client comes to me with a custom portal, a legacy database, or a use case that Zapier can’t reach, the V2 Email API is the only answer. I’ve set this up for real estate agencies in Dubai running property management platforms where lease events, payment triggers, and tenant onboarding emails all need to fire from external systems — systems GHL has no native connection to. That’s the real audience for the V2 API: developers and technical agencies building beyond the dashboard.What makes V2 meaningfully different from V1 is not just the cleaner endpoints — it’s the contact-centric model and the unified conversations namespace. Emails sent via the V2 API appear in the contact’s conversation thread, the same place your support team reads replies and your dashboard shows communication history. For agencies where multiple team members need visibility into a contact’s full journey, this is a significant operational advantage over V1’s more isolated send behavior.The authentication upgrade also matters more than it might seem. V2 uses standard Bearer token format with your V2 API key, but there’s a required Version header — 2021-04-15 — that catches a lot of developers off guard. Miss that header and you get a cryptic authentication error that wastes an hour of debugging. I tell every developer I train: the Version header is not optional, it is not legacy, and the documentation does not always lead with it prominently enough.Template support is where V2 becomes genuinely worth the setup effort. You build the email template inside GHL’s visual editor — properly branded, deliverability-tested, accessible to your non-technical team. Then you reference it by template ID in the API call and inject dynamic values through the customData object. The template stays clean and editable by anyone on the team. The personalization — invoice amounts, property addresses, appointment dates — gets passed in at send time from your external system. That separation is what I recommend to every agency building a white-label product on GHL.One thing I see constantly with agencies migrating from V1: they forget that V2 requires contacts to exist in GHL before sending. V1 was more permissive about ad hoc sending. V2 enforces the contact-first model for compliance and tracking reasons. If your external system is triggering emails for contacts that may not yet exist in GHL, you need a contact creation step before the email step — every time, without exception. Build that into your architecture early or you will debug 404 errors in production.
❓ Frequently Asked Questions
The GHL V2 Email API is used to send emails programmatically from external systems, custom applications, or code u2014 outside of GHL's native workflow builder. It is most useful for technical agencies and developers who need to trigger GHL emails from custom portals, external databases, legacy CRMs, or SaaS platforms that cannot connect to GHL through native integrations or Zapier. Emails sent through the V2 API use GHL's sending infrastructure and appear in the contact's conversation thread, keeping communication history unified.
In GHL, go to Agency Settings u2192 Integrations u2192 API Keys and generate a sub-account-level API key for the specific sub-account where your contacts live. Agency-level keys will not work correctly for email sends u2014 you need the sub-account scope. Once generated, use this key in the Authorization header as a Bearer token on every API request. Also include the Version header set to 2021-04-15, which is required for V2 endpoints to work correctly.
V2 uses a cleaner RESTful endpoint structure under the /conversations/messages namespace, standardized Bearer token authentication, and structured JSON error responses. V1 used an older authentication method that is being deprecated. V2 also enforces a contact-first model u2014 the recipient must exist as a GHL contact before you can send u2014 whereas V1 allowed some ad hoc sends. V2 has richer template support via templateId and customData, and emails sent through V2 appear in the contact's full conversation thread. All new integrations should use V2.
No. The V2 Email API requires the recipient to be an existing contact in your GHL sub-account. If the person does not exist yet, you need to create them first using the GHL Contacts API (POST /contacts/), then use the returned contactId in your email API call. For systems that process new leads or users who may not be in GHL yet, build a contact-creation step at the start of your workflow. Skipping this step is the most common cause of 404 errors in GHL email integrations.
GHL's V2 API enforces rate limits per sub-account, typically around 100 requests per minute. For high-volume transactional email systems, you should implement exponential backoff when you receive a 429 Too Many Requests response, and add a small delay (50-100 milliseconds) between sends in batch operations. Rate limits can vary by GHL plan, so if you are running an agency on a high-volume plan, check your specific limit with GHL support. Always log 429 responses so you can monitor whether your send volume is approaching the threshold.
Yes, the V2 Email API supports attachments via the attachments parameter, which accepts an array of attachment objects with file URLs. The files must be accessible via HTTPS URLs u2014 local file paths and base64-encoded content are not supported in the standard implementation. For most transactional use cases like invoices or reports, host the file in a cloud storage service (S3, Cloudflare R2, or similar) and pass the public URL in the API call. Keep attachment file sizes reasonable u2014 large attachments increase the chance of deliverability issues with recipient mail servers.
Yes. Because the V2 Email API sends under the /conversations/messages endpoint u2014 GHL's unified messaging namespace u2014 emails sent programmatically appear in the contact's conversation thread exactly like emails sent from the GHL dashboard. This is one of the key advantages of V2 over V1. Support teams and account managers can see the full communication history in one place, including API-triggered emails, without needing to check external systems or logs.
📘
New Book by Sawan Kumar
The AI-Proof Marketer
Master the 5 skills that keep you indispensable when AI handles everything else.
