Base de conhecimento GetMyBot

Email campaigns

Send an email to subscribers: choose a sender and audience, test the email, schedule it, and read the report. API and delivery events.

Nesta página

An email campaign sends a message to selected subscribers, such as a class invitation or a product update. First connect a sending domain and prepare the email in Content studio. Then choose an audience, check recipients, and schedule the send. Only people with the required consent receive it.

The campaign uses one specific published version of the email. Later edits to the draft do not change an already scheduled send.

What you need before the first campaign

Two things: a plan that includes the email channel, and a verified sending domain. Check them in that order.

A plan with the email channel

Email belongs to the bot builder, and the bot-builder line has four plans:

  • Start is free and does not include email;
  • Pro, Business and Enterprise are paid and each includes it.

The names are what trips people up: the free plan is called Start, and the cheapest paid one is called Pro.

No Customer Engagement plan grants email, not Communication, not Support, not Marketing, not Marketing Expert. The "Campaigns" line item in the last two means proactive messages and popups in the widget, not mail. The free bot-builder allowance that comes with a paid CE plan has no email either, because that allowance is the Start plan.

On a plan without the email channel the whole email surface is closed: sending domains, inbound routes, campaigns and their statistics. Every request to them answers 402 and names the missing capability (email). Check the plan before editing DNS: without the email channel you cannot add the sending domain at all, so configuring SPF, DKIM and DMARC would be wasted work. See Plans.

A verified sending domain

While the domain is unverified nothing is sent at all. Email from your own domain covers how to set one up.

Once both are in place, open the Email section and follow the Email campaigns link.

The editor

The campaign editor has four steps.

Email and sender. Enter a campaign name (up to 160 characters), sending domain, sender name, reply-to address, and subject (up to 255 characters). The preheader is a short line shown beside the subject in some inboxes; it can be up to 500 characters. Enter the reply-to as an address without a display name, such as hello@example.com. Line breaks are not allowed in the sender name, address, subject, or preheader because they could add unwanted email headers.

Content and preview. Pick a published email content version, or create one from a template. The campaign stores the document id together with the exact version number, so republishing the document later does not change a campaign that is already scheduled.

Audience and experiment. Choose all the bot's email subscribers or one ready segment, a group defined by rules. Optionally link an A/B experiment to compare email variants. When scheduled, the campaign records the current experiment version and uses it for the report.

Schedule and privacy. Send time, timezone mode, emails per minute (1 to 10 000) and the open-tracking switch. The send time is optional: launching a campaign without one starts it immediately.

There are two timezone modes. Campaign timezone sends to everyone at the same moment, for example 10:00 Moscow time. Recipient local time sends when each recipient's clock reads 10:00, so actual send times differ.

The timezone list is a fixed set of common zones (Moscow, Belgrade, London, Berlin, Dubai, Almaty, Tbilisi, Yerevan, Tashkent, Bangkok, Tokyo, New York, Los Angeles, UTC).

Daylight saving is handled explicitly:

  • the editor refuses a send time that does not exist in the campaign timezone on that date, and says so under the field;
  • in recipient mode, a recipient whose local wall time does not exist that day is reported as nonexistent_local_time by the recipient check, which blocks the launch until you pick another time;
  • when a wall time occurs twice, the earlier instant is used, consistently for everyone.

In recipient mode a person without a usable timezone is suppressed, so nobody receives mail at an arbitrary hour.

Recipient check before you send

Check recipients never sends anything. It builds the audience against the current draft and consent rules and answers with the number that would receive the campaign, the number suppressed and why, plus content errors and warnings. The answer uses raw codes, the same ones you will see in the interface.

An address is counted as suppressed when:

  • its subscription is not subscribed, and the reason is then the subscription state itself: unsubscribed, bounced or complained;
  • the address is empty or unusable (invalid_email);
  • the same normalised address already appears in this campaign (duplicate);
  • recipient-local mode is on and the person has no timezone (missing_timezone), an unrecognised one (invalid_timezone), or a local send time that does not exist that day (nonexistent_local_time);
  • consent was revoked between materialisation and the send attempt (no_consent).

Errors are what actually blocks the launch:

  • domain_not_verified: the sending domain is not verified;
  • content_not_published: the selected content version is missing or not published;
  • audience_not_ready: the chosen segment does not exist or has not finished computing;
  • experiment_not_ready: the linked experiment is not running, or its current version does not assign by subscriber;
  • scheduled_in_past: the send time has already passed;
  • nonexistent_local_time: see above;
  • empty_audience: nobody would receive the campaign;
  • every content error listed in Content studio, reported against content_document_id and the offending block.

Content warnings come through as well, plus one the campaign check adds itself:

  • missing_plain_text: the content has no readable text at all, only media or buttons, so the plain-text part of the message would be empty.

The campaign is ready to launch only when there are zero errors. Warnings never block it.

Send test email delivers the campaign's own content to one already verified, still consenting email identity of this bot. It never touches the campaign's recipient rows and never accepts a typed address, so it cannot consume or corrupt a scheduled send.

Launching and controlling

A campaign can only be launched from Draft. Confirm the launch in the editor. GetMyBot records the current email version, sender, audience, schedule, and experiment version, so later draft edits cannot change this send. If another team member edits the campaign at the same time, the editor checks its settings version (revision) and will not silently overwrite their work.

After that the campaign can no longer be edited. To change anything, use Create copy and launch the copy.

Statuses are Draft, Scheduled, Sending, Paused, Completed, Cancelled, Failed and Archived. Control actions and where they are allowed:

  • Pause: from Scheduled or Sending.
  • Resume: from Paused, back to Scheduled.
  • Cancel: from Draft, Scheduled, Sending or Paused. Recipients that have not been sent to are not sent to afterwards.
  • Archive: from Draft, Completed, Cancelled or Failed.

Pausing, resuming, canceling, and archiving also check the settings revision, so two team members cannot silently override each other's changes.

Emails are sent in batches at the chosen rate. If the sending process restarts, the campaign continues because its jobs are saved. Temporary failures are retried with an increasing delay from 15 seconds up to 15 minutes. If the email provider accepted a message but did not report the outcome, the recipient has Delivery unknown status. GetMyBot does not automatically send that email again, so the person will not get a duplicate.

Opens, clicks, and unsubscribes

For open tracking, GetMyBot may add a tiny invisible image to the email. Click and unsubscribe links also contain a signed token in an address such as https://<your-host>/e/t/<token>. A token is limited to one bot, campaign, and recipient and expires 90 days after sending. Its HMAC signature uses the installation's EMAIL_TRACKING_SECRET. If a separate tracking key is not configured, EMAIL_WEBHOOK_SECRET is used for compatibility. If neither is configured, the campaign cannot be sent. When rotating the key, account for existing links and the configured overlap period.

  • Optional open tracking uses a 1×1 GIF. Turning off "Collect open statistics" omits the image; delivery, clicks, complaints, and unsubscribes are still counted. The open count is imprecise, as explained in Email from your own domain.
  • Click tracking rewrites https:// link buttons only. A click token carries the destination, and the destination must itself be an https:// URL with a host and no embedded credentials, so the redirect cannot be pointed anywhere else.
  • Unsubscribe tokens carry no link id and no destination: such a token can opt someone out, but it cannot redirect anywhere.

An invalid, expired, cross-bot, or unknown token returns 404 without details. That response does not reveal whether a campaign or recipient exists.

Unsubscribing follows RFC 8058 one-click. A GET shows a plain HTML confirmation page with no JavaScript; a POST with the single form field List-Unsubscribe=One-Click performs it. Replaying the same unsubscribe counts as a success, because mail clients prefetch links and people click twice. The opt-out is recorded on the recipient row and as the canonical consent effect in the same transaction, so the link can never report success while consent stays subscribed.

Report

The campaign report separates: Recipients, Suppressed, Waiting, Sending, Accepted by provider, Delivery unknown, Delivered, Opened, Clicks, Bounced, Complaints, Unsubscribed, Failed and Cancelled. Clicked links are reported per link, and recipients can be listed page by page with their status and suppression reason.

Revenue linked to the campaign is shown separately for each method of crediting a purchase to an email (attribution model) and for each currency. Different models may credit the same purchase differently, so their figures are not added together. Amounts in different currencies are not combined either.

Replies from recipients

To have email replies reach support, set up an inbound route for an address on a verified domain. The part before @ is stored only as an irreversible hash, so the full address cannot later be viewed in the route list.

There is no dashboard screen for routes yet. If you need to receive replies, give the following command to a developer. The API token needs settings:read and settings:write:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/email/inbound-routes" \
  -H "Authorization: Bearer $PAT" -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com","local_part":"support"}'

The part before @ is lowercased and must match [a-z0-9][a-z0-9._+-]{0,62}. The domain must already be verified for this bot, otherwise the call returns 422; adding the same address again returns 409. The full address is returned once, when it is created; later the list shows only the domain. If the installation has no email webhook secret, the call returns 503 and inbound email is entirely disabled.

Incoming mail is normalised before it can touch a dialog:

  • the sender is resolved to a subscriber by the normalised address;
  • In-Reply-To and References are used to continue the existing thread, but only when the thread belongs to the same person;
  • quoted history is stripped from the body;
  • the raw message is capped at 8 MiB, the extracted text at 256 KiB, the subject at 255 characters and References at 32 entries;
  • at most 5 attachments of at most 1 MiB each are kept, stored under a content-addressed key; executable attachments (.bat, .cmd, .com, .dll, .exe, .msi, .scr and MS-DOS executable MIME types) are rejected;
  • an HTML-only message is reduced to text.

A message addressed to an unknown route is rejected with 404. That has a cost worth knowing in advance: the provider reads 404 as a failed delivery, so it will retry for hours and then report the failure to you. A mistyped address, or a route that does not exist, means hours of provider retries.

The reason lies in how routes are stored. A route's local part is kept as a hash computed with the installation's email webhook secret, and those hashes cannot be re-keyed, so after the secret is rotated no route can be found any more. Answering "accepted" would tell the provider the mail was delivered, and inbound mail would then vanish quietly: nothing would retry and nobody would find out. A refusal makes the breakage visible.

Practical consequence: if you see provider retries and complaints about inbound mail after rotating the email webhook secret, recreate the inbound routes, because the old ones can no longer match.

Provider contract

If you operate your own installation or write an adapter for an email service provider, these are the two public endpoints the provider talks to. Both authenticate with an HMAC-SHA256 signature over the raw request body, hex-encoded, in the X-Signature header, using the configured email webhook secret. A request with no signature is rejected with 401, and so is any request at all when no secret is configured: the endpoint fails closed.

Delivery and engagement events

POST /esp/{provider}/webhook, body limited to 1 MiB:

{
  "provider_id": "prv_00000000-0000-0000-0000-000000000000",
  "event": "delivered",
  "bounce_class": "hard",
  "url": "https://example.com/offer",
  "event_id": "evt_0000000001",
  "tag": "email-campaign:11111111-1111-1111-1111-111111111111:22222222-2222-2222-2222-222222222222"
}

This is the platform's own generic contract, not any one provider's native shape. Your adapter translates the provider callback into it.

  • event is one of delivered, opened, clicked, bounced, complained, unsubscribed. An unrecognised value is stored for inspection and changes no status.
  • bounce_class is hard or soft, and only meaningful for bounced.
  • tag is the stable metadata supplied at send time, in the form email-campaign:<campaign-id>:<subscriber-id>. It lets a callback that arrives before the provider id has been persisted still find its recipient.

Event to state mapping:

  • delivered: message and campaign recipient become Delivered;
  • bounced with bounce_class: hard: message Bounced, address suppressed, recipient Bounced;
  • bounced with bounce_class: soft: recorded only. A soft bounce says something about this attempt, not about the address, so it never suppresses and never moves the recipient;
  • complained: complaint recorded, address closed permanently;
  • unsubscribed: consent revoked, recipient Unsubscribed;
  • opened and clicked: recorded as events, no status transition.

An out-of-order callback can never walk a terminal state backwards.

Idempotency uses event_id when the provider sends one, and otherwise a SHA-256 of the raw body. The check, the effects and the receipt are written in one transaction, serialised per bot and key, so two concurrent deliveries of the same event cannot both apply.

Response codes tell your adapter what to do:

  • 200: understood. This includes events that were deliberately ignored, such as a duplicate or a message id this installation never sent: retrying will not change the outcome.
  • 400: malformed body, or provider_id/event missing.
  • 401: bad or absent signature.
  • 413: body over the limit.
  • 500: a transient failure on our side. This is the only class you should retry.

Inbound email

POST /esp/{provider}/inbound, body limited to 12 MiB:

{
  "event_id": "in_0000000001",
  "raw_mime": "<base64 of the original MIME message>"
}

The decoded MIME must not exceed 8 MiB. The answers are:

  • 200 with {"created": true|false}: the message was accepted; false means a duplicate of an already-recorded event_id.
  • 404: the recipient address matches no route. Retrying this one is worthwhile: the route may appear, and silently losing inbound mail is worse than extra retries. See "A message addressed to an unknown route" above.
  • 400: the envelope or MIME could not be parsed.
  • 401: the signature failed.
  • 413: the request body was over 12 MiB.

Neither endpoint ever returns provider credentials, recipient addresses that were not in the request, or the local part of an inbound route. Tracking and unsubscribe failures answer 404 without saying which check failed.

Troubleshooting

  1. Any email screen or request answers 402: your plan does not include the email capability. This is not a misconfiguration, and sending domains, inbound routes, campaigns and their statistics stay closed until the plan is Pro, Business or Enterprise. DNS records have nothing to do with it.
  2. Nothing sends and the domain card shows a warning: the sending domain is not verified yet. See Email from your own domain.
  3. "Campaign cannot be launched yet": open the recipient check and fix every error; warnings alone never block a launch.
  4. Many recipients suppressed as missing_timezone: the campaign is in recipient-local mode but your people have no timezone. Switch to campaign timezone or fill the profile field.
  5. The send time is refused, or the check reports nonexistent_local_time: that clock time does not exist on that date because of a daylight-saving jump. Pick another time.
  6. The open count seems wrong: tracking images cannot give an exact count of readers. Compare campaigns by clicks instead.
  7. Provider events never arrive: check that the adapter signs the exact raw body and that the webhook secret matches; an unsigned callback is answered with 401.
  8. The provider complains about repeated inbound deliveries: the address being written to matches no route. Check the route list, and if the email webhook secret was rotated recently, recreate the routes.

What's next