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.
| Transactional | Marketing | |
|---|---|---|
| Who sends it | Your system, through the API | You, from the dashboard |
| To whom | One person at a time | A list or segment |
| When | At the moment of the event | At the time you choose |
| Examples | Password, order, payment slip (boleto), access code | Newsletter, promotion, launch |
| Unsubscribe | Does not apply to service messages | Required, 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.
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.
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.
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.
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.
| Event | When it arrives | What to do |
|---|---|---|
| delivered | The recipient's provider accepted the message | Mark it as delivered in your system |
| bounce | The message was refused; bounce_classification gives the reason | If it is permanent, ask the person for another address |
| spamreport | The recipient marked it as spam | Do not resend; the address is already suppressed |
| open | The message was opened; machine_open flags antivirus and prefetch opens | Leave machine opens out of your open rate |
| click | A link was clicked; the url field says which one | Tie the click to the record through the metadata |
| unsubscribe | The recipient asked to unsubscribe | Reflect 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 plansTransactional 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.