Skip to main content

Quickstart

Send your first transactional email through the public API, check its status, and learn where to go next. This guide is for anyone integrating EmailMassivo for the first time.

Before you start​

  • A EmailMassivo account and a verified domain in the dashboard.
  • An enabled default key of that domain — the email from step 2 goes through it.

How to assign and change the default key is covered in Sending keys.

Step 1. Create a token​

Issue a token with the email.send and email.read scopes — there's a step-by-step walkthrough in Authentication → Creating a token. Save the value right away: it's shown only once.

Put the token in an environment variable — substitute your full value, starting with rs_ck_v1_:

export API_TOKEN="rs_ck_v1_..."

Step 2. Send an email​

The minimal body is a sender, a recipient, a subject, and html. In the example, replace noreply@yourdomain.com with an address in your verified domain, and you@example.com with your own mailbox: that's where the email arrives. You don't need to pass the key id: the email goes through the default key of the sender's domain.

async function main() {
  const response = await fetch('https://api.emailmassivo.com/api/v1/public/emails', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.API_TOKEN}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': 'quickstart-1',
    },
    body: JSON.stringify({
      data: {
        from: { email: 'noreply@yourdomain.com' },
        to: { email: 'you@example.com' },
        subject: 'My first email via the API',
        html: '<h1>It works!</h1>',
      },
    }),
  });

  console.log(response.status, await response.text());
}

main().catch(console.error);

Step 3. Check the response​

A successful response is 202 Accepted:

{
  "ok": true,
  "data": {
    "id": "0199b2f4-6c1e-7a3d-9f2b-4e8c1d7a5b60",
    "status": "queued",
    "createdAt": "2026-09-30T10:15:00.000Z",
    "recipients": [
      {
        "id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e01",
        "email": "you@example.com",
        "name": null,
        "type": "to",
        "status": "queued",
        "reason": null
      }
    ]
  },
  "meta": { "requestId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-09-30T10:15:00.120Z" }
}

data.id is the email identifier: store it to track what happens to the send. The Idempotency-Key header protects against duplicates: if you repeat the request with the same key, no second email goes out. To send the example again, change the value — for example, to quickstart-2. See Idempotency and quota for details.

If the response is an error, look up its error.code in Send error codes. The most common errors on a first request are SENDER_DOMAIN_MISMATCH (the sender address isn't in the key's domain) and SENDING_KEY_NOT_ACTIVE (the key isn't enabled yet). 401 and 403 errors concern the token — see Authentication → Handling errors.

Step 4. Check the email status​

Save data.id from the step 3 response in an environment variable — the example uses the value from the response above; substitute your own:

export EMAIL_ID="0199b2f4-6c1e-7a3d-9f2b-4e8c1d7a5b60"
async function main() {
  const response = await fetch(`https://api.emailmassivo.com/api/v1/public/emails/${process.env.EMAIL_ID}`, {
    headers: {
      'Authorization': `Bearer ${process.env.API_TOKEN}`,
    },
  });

  console.log(response.status, await response.text());
}

main().catch(console.error);

Once the recipient's mail server confirms receipt, the recipient status becomes delivered. What the other statuses mean is covered in Email statuses and events.

What's next​