Skip to content
Book a demoStart free trial (opens in a new tab)
Start free trial (opens in a new tab)Book a demo
Docs

Send white-label email with SendGrid

Connect your SendGrid account to Voice AI Portal with one API key, and every email the portal sends for your agency goes out through SendGrid from your own domain: sign-in codes, client user welcomes, team invites, client billing emails and outbound email campaigns. When you save, the portal also adds a delivery webhook to your SendGrid account, so it records whether each email is delivered, bounced, blocked or marked as spam.

This guide is one of five sender guides. For a comparison, see Configure custom email.

What you need first

Section titled “What you need first”
  • Owner access. The Email Hub is in Settings, which only the agency owner opens.
  • A SendGrid account that can send email.
  • Access to your domain’s DNS, to authenticate your sending domain.
  • A From address on that domain, for example hello@youragency.com.

Step 1: Authenticate your domain in SendGrid

Section titled “Step 1: Authenticate your domain in SendGrid”

SendGrid sends only from an authenticated domain or a verified single sender. For client email, authenticate the domain.

  1. Start domain authentication

    In SendGrid, go to Settings, then Sender Authentication, and select Get Started under Domain Authentication. Choose your DNS host and enter your domain.

  2. Add the DNS records

    SendGrid shows the records to add, usually CNAME records. Together they set up SPF (which servers may send for your domain) and DKIM (a signature that proves each email came from your domain). Add each one at your DNS host exactly as shown. On Cloudflare, set them to DNS only.

  3. Verify

    Back in SendGrid, select Verify. DNS changes can take a while to show; try again later if it doesn’t verify straight away.

  4. Add DMARC (recommended)

    If your domain has no DMARC record, add a TXT record named _dmarc with the value v=DMARC1; p=none;. It tells mailbox providers what to do with email that fails the checks.

SendGrid’s guides: Configure domain authentication (opens in a new tab) and Enforce authentication with a DMARC policy (opens in a new tab). A verified single sender also works for testing; SendGrid recommends domain authentication for production.

Step 2: Create a SendGrid API key

Section titled “Step 2: Create a SendGrid API key”

In SendGrid, go to Settings, then API Keys, and create a key named, for example, Voice AI Portal. Copy it straight away: SendGrid shows it only once.

Permission Why the portal needs it
Mail Send To send your emails. The portal won’t save a key without it.
Event Webhook To add the delivery webhook that reports delivered, bounced and spam emails. Without it, sending still works and delivery tracking stays off.

Full Access includes both. A restricted key with just these two permissions is the safer choice.

If your account is an EU regional subuser, create the key in that subuser.

Step 3: Connect SendGrid in the Email Hub

Section titled “Step 3: Connect SendGrid in the Email Hub”

  1. Open the Email Hub

    Go to Settings and open the Email Hub tab. In Your email sender, under How you send, select SendGrid.

  2. Fill in the fields

    Field What to enter
    SendGrid API key The key you created (it starts SG.). It is encrypted at rest and never shown again. When you edit other fields later, leave it blank to keep the saved key.
    Region Global (most accounts), or EU (EU regional subusers) for an EU regional subuser.
    Reply-to Email Where client replies go, for example support@youragency.com.
    From Name Your agency name as clients see it.
    From Email An address on your authenticated domain, or your verified single sender.

  3. Select Save Sender Settings

    The portal checks the key with SendGrid first: if SendGrid refuses it, nothing is saved and you see the reason. It then adds the delivery webhook to your SendGrid account and shows Connected to SendGrid and saved. The card shows Connected: SendGrid and the delivery tracking line.

If you change the Region later, enter the key again.

Step 4: Send a test email

Section titled “Step 4: Send a test email”

Enter an address next to Send Test Email and select Send Test Email. When SendGrid sends it from your address, the badge changes from Send a test email to confirm to Test email accepted. Check that the email arrives from your From Email and that a reply goes to your Reply-to Email.

If the message says the test went out from the platform address, SendGrid refused it and the message gives SendGrid’s reason, for example a From address that isn’t authenticated. You can send up to 10 test emails an hour.

How does delivery tracking work?

Section titled “How does delivery tracking work?”

When you save, the portal creates an event webhook in your SendGrid account named Voice AI Portal delivery tracking, pointing to app.voiceaiportal.com with a private address for your agency. SendGrid signs every event, and the portal checks the signature before recording anything. You don’t need to copy or paste the webhook, and you shouldn’t edit or delete it in SendGrid.

SendGrid event What the portal records
Delivered Delivered
Bounce or Blocked Failed, with SendGrid’s reason
Dropped Failed, with SendGrid’s reason
Deferred Delivery delayed (SendGrid keeps trying)
Spam report Marked as spam

Opens and clicks are not tracked, and open and click tracking stay off for these emails, so sign-in links always work exactly as sent.

The Email Hub shows Delivery tracking on. Last update with the time the last event arrived, or Updates appear after your next email before the first one. If it shows Delivery tracking off, sending still works and the reason is shown. The most common reason is a key without the Event Webhook permission: give the key that permission, or create a new key, then save again with the key.

What happens if SendGrid can’t send an email?

Section titled “What happens if SendGrid can’t send an email?”
  • SendGrid refuses it (for example an unauthenticated From address or a revoked key): the email goes out from the Voice AI Portal address instead, under your From Name and with your Reply-to Email, so your client still gets it.
  • SendGrid is busy or briefly unavailable: the portal retries before it moves to the platform address.
  • The recipient’s address is invalid: the email is not sent from another address, because no sender could deliver it.
  • Outbound email campaigns never use the platform address. If SendGrid refuses a campaign email because of your setup, the campaign pauses with the reason. See Email campaigns.

Can I send email campaigns through SendGrid?

Section titled “Can I send email campaigns through SendGrid?”

Yes. An email campaign playbook is ready once the Email Hub shows Test email accepted. Until then, the playbook shows “Verify your sending domain in Settings → Email Hub first”, and clients cannot choose it. Send a test email after any change to your From Email. See Email campaigns.

Troubleshooting

Section titled “Troubleshooting”
Problem What to do
“This API key cannot send email: give it the “Mail Send” permission. Nothing was saved.” Edit the key in SendGrid to add Mail Send, or create a new key, then save again.
“SendGrid rejected this API key (…). Nothing was saved.” Copy the key again with no spaces, check it still exists in SendGrid, and check the Region matches the account.
“Couldn’t reach SendGrid (…). Nothing was saved.” Wait a moment and save again.
“Enter the SendGrid API key again: it is needed when the account settings change” You changed the Region. Paste the key and save.
Delivery tracking off: “SendGrid didn’t accept the delivery webhook (…)” Give the key the Event Webhook permission, or check your SendGrid plan’s webhook limit, then save again with the key.
Delivery tracking off: “SendGrid didn’t turn on webhook signing (…)” Check the key’s Event Webhook permission, then save again with the key.
The test went out from the platform address Read SendGrid’s reason. Usually the From Email isn’t on an authenticated domain or verified sender.
The badge stays on Send a test email to confirm Send a test email. The badge changes once SendGrid sends it from your address.
“Too many changes to your email settings. Try again in an hour.” The Email Hub accepts 10 saves an hour.

Switch or disconnect

Section titled “Switch or disconnect”

Select Disconnect SendGrid and confirm. The saved key is removed, the delivery webhook is removed from your SendGrid account, and your emails go out from the platform address straight away. Your sender details stay. Switching to another sender also removes the webhook.

Section titled “Related”