SMTP2GO

This page is for a store sending through SMTP2GO that wants delivered, bounced and complained figures on its campaign screens. Read Delivery reports and providers first for what a provider webhook is and what the store does with each event.

Before you begin

• An SMTP2GO account with a verified sender. Since 11 April 2025 SMTP2GO requires every message to come from a verified sender domain or a verified sender address.
• An API key beginning api-.
• The grav-plugin-email-smtp2go plugin at 1.1.2 or later, with the Grav Email plugin at 5.2.0 or later on PHP 8.1 or later.
• The Email plugin's Mail Engine set to SMTP2GO.

What the API key must be allowed to do

In SMTP2GO, go to Sending → API Keys, open the key, and tick these three on its Permissions tab.

Leave Statistics, Activity, Suppressions, Templates, SMTP Users and API Keys unticked. Nothing here uses them.

Fill API Key in even on the SMTP transport. The Set up button and the domain lookup use it.

Configure the transport

The transport is a Grav plugin, so its own settings live in the Grav admin's plugin list. The webhook that reports deliveries back is set up from the Providers card in the KahunaCart admin, in the next section.

1. 1

   In the Grav admin's plugin list, open Email SMTP2GO and set Transport to API (faster) or SMTP.

2. 2

   Paste your API key into API Key.

   It begins api-. On the SMTP transport you also need Username, Password, Port and TLS. SMTP users are created in SMTP2GO under Sending → SMTP Users.

3. 3

   Open Email in the same plugin list and set Mail Engine to SMTP2GO.

There is no verification key field. SMTP2GO does not sign its webhooks; see What protects the address.

Set the webhook up in one click

1. 1

   Check Settings → Webhooks in SMTP2GO for a webhook you already have.

   On a free plan there is room for one. If something else is using it, read the warning above before going further.

2. 2

   Go to KahunaCart → Add-ons → Newsletters → Settings → Providers and click Generate a secret on the SMTP2GO card.

3. 3

   Click Set up in SMTP2GO.

The button reads your existing webhooks first, then creates one with four things set:

• the webhook address, with your secret in it;
• the six events below;
• the output type set to JSON, because the store cannot read SMTP2GO's default form encoding;
• X-Grav-Send-Id in the header list, because SMTP2GO only echoes a header named on the webhook itself.

Pressing it twice adds nothing. Nothing is ever deleted.

Do it by hand instead

1. 1

   In SMTP2GO, go to Settings → Webhooks → Manage Webhooks and click Add Webhook.

2. 2

   Paste the webhook address from the Providers card into URL, and under Users select the SMTP users, API keys or authenticated IPs this webhook should fire for.

3. 3

   Set Output type to JSON.

   This one matters more than it looks. Leave it on form encoded and SMTP2GO's dashboard shows a healthy webhook while the store cannot read a word of it.

4. 4

   Under Email events to include, tick Delivered, Bounce, Spam, Open, Click and Reject.

5. 5

   In Email headers, add X-Grav-Send-Id, then click Save changes.

   The box takes several entries, separated by pressing Tab. SMTP2GO is the only provider that echoes a header back, and it only echoes one that is named here.

If you set an Authorization header on the webhook, put the whole value, including the word Bearer or Basic, into providers.smtp2go.auth_header in user/config/plugins/kahunacart-newsletters.yaml. The store checks it in constant time alongside the path secret.

What each event means

unsubscribe is not acted on. SMTP2GO reports it when somebody uses SMTP2GO's own unsubscribe link, and the store carries its own List-Unsubscribe.

What a reject means

SMTP2GO sends a reject when it refuses to send at all. Its documentation gives three causes: the address has previously hard bounced, complained or unsubscribed; the sender is not verified; or the SMTP user, API key or authenticated IP is set to Sandboxed.

The first is a refused address: the store suppresses it and marks the subscriber bounced. The other two are a refused message: the send is marked bounced and the subscriber is left as they were.

The store reads the event's message to decide. A message naming an unverified sender is the message. One naming the suppression list, a previous bounce, a complaint or an unsubscribe is the address. Anything else is read as the message, because one more refused message costs less than losing a subscriber.

Provider quirks

SMTP2GO only echoes a header you registered on the webhook. Subject and Message-id come back by default; anything else has to be named in the webhook's Email headers box. The Set up button does that for you. If you rename the send header, press Set up again.

On the API transport, the Message-ID you see back is SMTP2GO's, not yours. So on that transport the send header is the correlation that works. On the SMTP transport the whole message goes over the wire and your Message-ID survives.

Nothing is signed. SMTP2GO publishes no signature scheme for its webhooks. The path secret, and the optional Authorization header, protect the address.

SMTP2GO retries a failed post. Up to 35 times over 48 hours, with a ten-second timeout on each attempt.

One event per request. The payload is flat, with no envelope and no batching.

What protects the address

The webhook address carries thirty-six random bytes minted by Generate a secret. A wrong secret answers 404 rather than 401, so a scanner cannot tell a wrong secret from a provider you do not use. SMTP2GO also offers an Authorization header on the webhook and publishes an A record at webhooks.smtp2go.com for allowlisting its own delivery addresses.

DNS for the Health tab

SMTP2GO verifies a sender domain with three CNAMEs, and hands you all three during setup.

<id> is an SMTP2GO-assigned number for that domain. It is the same number in the em and s records.

If you need -all at the end of your own SPF record, SMTP2GO gives return-alt.smtp2go.net as the return-path value instead.

DMARC is yours to add. SMTP2GO does not publish it for you. See Health.

With the Sender Domains permission on the key, the Health tab reads the selector and the return path off your account. Without it, put the part before ._domainkey into deliverability.dkim_selector on KahunaCart → Add-ons → Newsletters → Settings → Health.

Checking it actually works

Send a one-recipient campaign to an address you can read, open it, press a link, then look at the SMTP2GO card. That is the only check that tells a working webhook apart from a well-drawn screen.

Troubleshooting

Related

• Delivery reports and providers
• Health
• Campaigns
• Settings reference
• Emails