1. Five-Minute Quickstart

  1. Sign in to your Client Portal and click + New Project.
  2. Open your project → add your sending domain (e.g. yourdomain.com) → copy the 6 DNS records to Cloudflare / Namecheap / GoDaddy.
  3. Click Verify Now until status turns verified (Cloudflare tip: keep the three _domainkey CNAMEs DNS only / grey cloud).
  4. Generate an API key (vm_live_...), save it in your app's .env as VINMAIL_API_KEY, and send your first email below!

2. Sending Transactional Email

export async function sendOtpEmail(to: string, code: string) {
  const res = await fetch('https://vinmail-api.vinworlddev.com/v1/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VINMAIL_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `otp-${to}-${code}`,
    },
    body: JSON.stringify({
      from: 'YourApp <[email protected]>',
      replyTo: '[email protected]',
      to,
      subject: 'Your verification code',
      text: `Your verification code is ${code}. It expires in 10 minutes.`,
      html: `<p>Your verification code is <strong>${code}</strong>.</p>`,
    }),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err?.error?.message ?? `VinMail HTTP ${res.status}`);
  }
  return res.json(); // { id, status: "queued" }
}
API Base URL: https://vinmail-api.vinworlddev.com
Check Delivery Status: GET /v1/emails/:id with the same Authorization: Bearer vm_live_... header.

3. Custom Domain Mailboxes & Mobile App

Want real business inboxes like [email protected] or [email protected] that you receive and reply to on your phone?

  1. In your dashboard, open Mailboxes and click Enable Receiving / Check MX next to your verified domain.
  2. Add the displayed MX record on your domain's DNS (10 inbound-smtp.eu-west-1.amazonaws.com). Note: a domain can only have one root inbound email provider.
  3. Create one or more mailboxes (e.g. [email protected], [email protected]) or add Aliases to route multiple addresses into one inbox.
  4. Create a Mobile App Login, assign it to one or more mailboxes, and sign in inside the VinMail Flutter mobile app.

4. Common API Status & Error Codes

HTTPCodeMeaning
202queuedAccepted and queued for immediate delivery.
401invalid_api_keyMissing, malformed, or revoked vm_live_ key.
403project_suspended / organization_suspendedProject or organization is paused. Check your dashboard status.
422domain_not_verifiedThe from domain is not verified on this project.
422all_recipients_suppressedAll recipients previously hard-bounced, complained, or were suppressed.
429limit_exceeded / rate_limitedDaily/monthly quota or per-second burst limit reached.