Transactional email

Transactional email through the API, in the same account as your campaigns

Order confirmations, password resets and billing notices going out from your system through a REST API, on the same meter as your campaigns.

What transactional email is

Transactional email is the message your system sends to a person because of something they did: created an account, made a purchase, asked to change their password, received a bill. It goes to one recipient at a time, at the moment of the event, and the person expects to receive it.

Email marketing is the opposite: the same message to a list, at the time the company chooses. That is why the two usually live in separate tools, with two bills and two dashboards to track delivery.

Difference between transactional email and email marketing
TransactionalMarketing
Who sends itYour system, through the APIYou, from the dashboard
To whomOne person at a timeA list or segment
WhenAt the moment of the eventAt the time you choose
ExamplesPassword, order, payment slip (boleto), access codeNewsletter, promotion, launch
UnsubscribeDoes not apply to service messagesRequired, in one click

In WiseData Mail both go out from the same account and the same authenticated domain, and count on the same sends meter.

Two ways to send through the API

Pick a template built in the platform or send ready-made content in the call. The response comes back right away; delivery status arrives later, through the webhook.

  • Platform template: build the transactional email in the dashboard, and the call carries only the template key and the variables (name, order number, link). Changing the copy does not require touching your system.
  • Content in the call: if you prefer to keep the email in your own code, send the subject, HTML and plain-text version straight to the API.
  • 202 when the message enters the queue; 200 when the same idempotency key was already used, without sending again.
  • Up to 10 attachments per message, 10 MB in total, also together with a platform template: the confirmation saved in the dashboard, with the invoice PDF in the call.
  • Tags and metadata come back in every webhook event, so you can tie the delivery to the order.

Transactional email examples

The six types almost every system needs to send, each with the precaution that prevents the most common problem.

  • Sign-up and email confirmation

    A welcome message and a link to confirm the address right after sign-up. Tip: the link should expire and work only once. Send it at sign-up time, never in a batch at the end of the day.

  • Password reset

    A link to create a new password. Tip: short validity, single use and no password in the body. On the "forgot password" screen, show the same message whether or not the account exists.

  • Access code

    A two-step verification or passwordless login code. Tip: the code goes in the body, never in the subject, because the subject shows up in the lock screen notification.

  • Order confirmation

    Order number, items, total and next steps. Tip: use the order id in the Idempotency-Key. If your system repeats the call, the customer does not get two confirmations.

  • Billing, invoice and receipt

    Invoice, payment slip, receipt and due date reminder. Tip: attach the PDF (up to 10 MB in total) or send a link to the logged-in area. Keep the invoice id in the metadata to reconcile through the webhook.

  • System notice

    New sign-in to the account, email change, updated terms, a failed integration. Tip: say what happened and what the person should do, with a single button. No promotion attached.

How delivery works

From the API call to the event reaching your system, in four steps.

  1. Your system calls the API

    POST /v1/emails with the API key. The 202 response carries the message id; with the same Idempotency-Key, the response is 200 and nothing goes out again.

  2. The account checks before sending

    An address already suppressed because of a permanent bounce or complaint comes back with the status suppressed. With no quota left in the cycle, the API refuses the call with 403 instead of queuing it.

  3. The message goes out from your domain

    Signed with the DKIM of your authenticated domain. The recipient's provider accepts it (delivery) or refuses it (bounce), and the result becomes an event.

  4. Events reach your webhook

    Delivery, open, click, bounce, complaint and unsubscribe, in batches of up to one hundred, signed and retried automatically if your server does not respond.

Webhook events

Each event carries the type, the time, the address, the message id and the tags and metadata you sent with the message. The campaign_id field is null for transactional email, and message_type tells whether the message was transactional or marketing.

Webhook event types and what to do with each one
EventWhen it arrivesWhat to do
deliveredThe recipient's provider accepted the messageMark it as delivered in your system
bounceThe message was refused; bounce_classification gives the reasonIf it is permanent, ask the person for another address
spamreportThe recipient marked it as spamDo not resend; the address is already suppressed
openThe message was opened; machine_open flags antivirus and prefetch opensLeave machine opens out of your open rate
clickA link was clicked; the url field says which oneTie the click to the record through the metadata
unsubscribeThe recipient asked to unsubscribeReflect the preference in your own records

Events arrive in batches of up to one hundred, signed with the endpoint secret. The full example of a batch is in the help center.

Outcomes simulated by the sandbox inbox reach the same endpoint, signed the same way, with is_test: true. Filter on that field so a test bounce never unsubscribes a real customer.

Transactional email best practices

Transactional email is the email the person is waiting for. If it lands in spam or arrives twice, the problem becomes a support ticket. These six practices solve most cases.

1. A sender separate from marketing

Use a dedicated address for transactional email, such as orders@ or account@, not the newsletter address. If your plan includes more than one domain, a subdomain only for transactional email (for example, notices.yourcompany.com) separates the reputation of the two in the eyes of mailbox providers: a campaign with many complaints does not drag the password reset into spam.

2. No sensitive data in the subject

The subject shows up in the phone notification, in the inbox list and in the logs of whoever processes the email. No access code, password, ID number or card number in the subject. "Your access code" is enough; the code goes in the body.

3. Always include a plain-text version

Send the text field along with html. Screen readers, watches and some corporate email clients display the plain-text version, and leaving it out counts against the message in spam filters.

4. Idempotency on every call

A queue that retries, a timeout that triggers a new attempt and a double click on a button all produce the same call twice. Derive the Idempotency-Key from the internal id (order-48213-confirmation) and reuse the same key on every retry. The API returns the previous message with 200 and does not send another one.

5. Handle the webhook the right way

  • Check the signature: HMAC-SHA256 of the timestamp, a dot and the raw body, with the endpoint secret, compared with the X-WiseData-Signature header.
  • Reject old timestamps, so a captured batch cannot be replayed later.
  • Respond 2xx quickly and process in a queue. A slow response turns into a retry.
  • Discard repeats by X-WiseData-Delivery (the batch) and by each event's id.
  • Do not assume order: use occurred_at so you never replace a newer state with an older one.

6. Do not mix marketing into transactional email

A promotional banner in the footer of an order confirmation turns a service message into a commercial one: it now requires unsubscribe and consent, and the complaints it generates land on the channel that delivers the password. Promotions go out as campaigns, to people who agreed to receive them.

Is your domain not authenticated yet? Read the SPF, DKIM and DMARC guide.

What comes with the API

  • Signed webhooks

    Delivery, open, click, bounce, complaint and unsubscribe events arrive in batches of up to one hundred, signed, with automatic retries and secret rotation.

  • Sandbox inbox

    A test key simulates delivery, bounce and complaint without sending anything out. You can test your webhook receiver before going to production.

  • Scoped keys

    Each key gets only what it needs: read contacts, write contacts, delete contacts or send email.

  • Contacts through the same API

    Create or fix contacts by your system's identifier and add them to lists, so campaigns use the same contact base.

  • Machine opens flagged

    Opens and clicks made by antivirus scanners or prefetching come flagged, so they do not inflate your numbers.

  • PHP SDK and Laravel transport

    Open source PHP client (MIT). In Laravel, sending goes through WiseData Mail by changing the mailer in .env.

Why keep both in one account

  • Marketing and transactional email with the same vendor and on the same meter.
  • Pre-send check and health panel for transactional email too.
  • Sending reputation isolated per account: another customer's problem does not affect your delivery.
  • Unlimited contacts and no overage charges: at the end of the quota, sending pauses instead of billing extra.

Which plans include it

The API is included in the Volume plan (R$ 799, 400k sends). The free trial does not include the API.

See plans

Transactional email questions

What is the difference between transactional email and email marketing?

Transactional email is triggered by your system because of something the person did (sign-up, purchase, password change) and goes to one recipient at a time. Marketing is the same message to a list, at the time the company chooses. In WiseData Mail both go out from the same account.

Does transactional email need consent?

A service message tied to an account, order or contract does not depend on marketing consent and does not require unsubscribe. That holds only while it remains a service message: with a promotion inside, it becomes commercial email.

Do you offer SMTP?

No. Sending is through the REST API and the dashboard. In Laravel, the PHP SDK replaces SMTP without changing the code that calls Mail.

Does transactional email have an unsubscribe link?

Service messages, such as password and order emails, do not require unsubscribe. If the address is already suppressed because of a permanent bounce or complaint, the API returns the status suppressed instead of sending.

How do I avoid sending the same message twice?

Send the Idempotency-Key header. If the same key arrives again, the API returns the previous message with status 200 and does not send another one.

How do I know the email was delivered?

Through the webhook, which sends the delivered event when the recipient's provider accepts the message and bounce when it refuses it. In the dashboard, the contact timeline shows every send and the reason for each failure.

Can I test the integration without sending to real customers?

Yes. The sandbox inbox test key simulates delivery, bounce and complaint without sending anything out, and the events reach your webhook with is_test: true.

How much does transactional email cost?

Each message counts as one send on the same meter as your campaigns. The API is on the Volume plan, R$ 799 per month with 400k sends. If you hit the quota, the API refuses new sends until the next cycle: there are no overage charges.

Start with the free trial

Explore the dashboard and authenticate your domain with no card. The API and the sandbox inbox come with the Volume plan.