Send your first email
From nothing to a delivered email, with the DNS explained rather than assumed.
Get a key
Signing up returns a working test key in the same response. A test key accepts every request, charges nothing, sends nothing and skips DNS verification, so you can write the whole integration before your domain is live.
curl -X POST https://api.woyra.io/v1/emails \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: first-send' \
-d '{
"to": "alex@example.com",
"from": "hello@yourdomain.com",
"subject": "Your code",
"text": "Your code is 483920"
}'No library is needed: it is one HTTPS request, so it works from any language. Here is the same send from Node.js with its built-in fetch. Keep the key in an environment variable such as WOYRA_API_KEY, never in your code.
const res = await fetch('https://api.woyra.io/v1/emails', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WOYRA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'first-send',
},
body: JSON.stringify({
from: 'hello@yourdomain.com',
to: 'alex@example.com',
subject: 'Your code',
text: 'Your code is 483920',
}),
});
console.log(await res.json());Or use an official library: Node.js (npm install @woyraemail/node), Python (pip install woyra), PHP (composer require woyra/woyra-php) or Go (go get github.com/minacgroup/woyra-go). Each reads WOYRA_API_KEY from the environment, sets the idempotency key for you, retries what is safe to retry, raises a typed error, and verifies webhook signatures.
import { Woyra } from '@woyraemail/node';
const woyra = new Woyra(); // reads WOYRA_API_KEY
const email = await woyra.emails.send({
from: 'hello@yourdomain.com',
to: 'alex@example.com',
subject: 'Your code',
text: 'Your code is 483920',
});
console.log(email.id, email.status);import woyra
client = woyra.Woyra() # reads WOYRA_API_KEY
email = client.emails.send({
"from": "hello@yourdomain.com",
"to": "alex@example.com",
"subject": "Your code",
"text": "Your code is 483920",
})
print(email["id"], email["status"])<?php
require 'vendor/autoload.php';
$woyra = new Woyra\Client(); // reads WOYRA_API_KEY
$email = $woyra->emails->send([
'from' => 'hello@yourdomain.com',
'to' => 'alex@example.com',
'subject' => 'Your code',
'text' => 'Your code is 483920',
]);
echo $email['id'], ' ', $email['status'];client := woyra.NewClient(os.Getenv("WOYRA_API_KEY"))
email, err := client.Emails.Send(ctx, &woyra.SendEmailParams{
From: "hello@yourdomain.com",
To: woyra.Recipients{"alex@example.com"},
Subject: "Your code",
Text: "Your code is 483920",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(email.ID, email.Status)Verify the domain you send from
Live email needs a domain you have proved you control. Add it and Woyra generates the DKIM key and hands you every record, ready to paste, with the exact value each one needs.
curl -X POST https://api.woyra.io/v1/domains \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-d '{"domain": "yourdomain.com"}'- A TXT record at <selector>._domainkey.yourdomain.com carrying the DKIM public key. Sending is blocked until this resolves.
- A TXT record at the apex with an SPF include. If you already publish SPF, add the include term to the record you have: a domain with two SPF records fails SPF entirely.
- A DMARC record at _dmarc.yourdomain.com, in report-only mode to start. Advisory, and worth doing before you raise volume.
- An MX record, optional, which makes every address on the domain receive as well as send.
Publish them, then ask Woyra to check. Verification is safe to repeat: a customer who checks too early simply checks again, and each record reports its own result, because a missing DKIM record and a duplicate SPF record need completely different fixes.
curl -X POST https://api.woyra.io/v1/domains/dom_01J.../verify \
-H "Authorization: Bearer $WOYRA_KEY"Send, and see what happened
A send is accepted in well under a second and delivered asynchronously: the API never makes you wait on a relay. Poll the message, or register a webhook and be told. Reading an email back includes its events: every status it has had and when, so "did it arrive?" is one request.
curl https://api.woyra.io/v1/emails/email_01J... \
-H "Authorization: Bearer $WOYRA_KEY"Watch the whole integration
The same steps from your own code, then deploying with the key on your host, a signed webhook and the switch to a live key.
Questions
Do I need a verified domain to start?
No. A test key skips DNS entirely, so you can build and test the whole flow first. You need a verified domain only to send live mail, because mail from an unverified domain damages the sending reputation every customer shares.
How long does DNS verification take?
As long as your DNS provider takes to publish, usually minutes and at most an hour. Woyra re-checks on demand, so there is nothing to wait for on our side.
What does email cost?
Email plans are monthly subscriptions: Starter, $4.99 a month for up to 10,000 emails; Growth, $9.99 for up to 25,000; Business, $14.99 for up to 50,000; Scale, $24.99 for up to 75,000; and Pro, $34.99 for up to 100,000. You choose a plan on the Billing page of the console (or PUT /v1/billing/email_subscription); it is paid from your balance at once and renews every month from the day you took it, whether or not you send, until you cancel. The plan's emails reset each billing month. A bigger plan applies at once for the difference; a smaller one starts at the next renewal. Past the plan's emails, sending stops with email_limit_reached unless you turn on overage, which charges $0.40 per 1,000. Without a plan you can send 1,000 emails a month free, at most 100 a day. If a renewal cannot be paid, the account sends on the free 1,000 until the balance can pay it, and it renews within the hour of a top-up. Above 100,000 a month we agree a price with you. Test-mode mail is always free.
Next
Get a test key and run any of this in about ninety seconds.