DEVELOPER DOCUMENTATION
VinMail Integration Guide
Everything onboarded developers need to verify domains, send transactional emails, and provision custom-domain mobile mailboxes.
1. Five-Minute Quickstart
- Sign in to your Client Portal and click + New Project.
- Open your project → add your sending domain (e.g.
yourdomain.com) → copy the 6 DNS records to Cloudflare / Namecheap / GoDaddy. - Click Verify Now until status turns verified (Cloudflare tip: keep the three
_domainkeyCNAMEs DNS only / grey cloud). - Generate an API key (
vm_live_...), save it in your app's.envasVINMAIL_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:
Check Delivery Status:
https://vinmail-api.vinworlddev.comCheck 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?
- In your dashboard, open Mailboxes and click Enable Receiving / Check MX next to your verified domain.
- Add the displayed
MXrecord on your domain's DNS (10 inbound-smtp.eu-west-1.amazonaws.com). Note: a domain can only have one root inbound email provider. - Create one or more mailboxes (e.g.
[email protected],[email protected]) or add Aliases to route multiple addresses into one inbox. - 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
| HTTP | Code | Meaning |
|---|---|---|
| 202 | queued | Accepted and queued for immediate delivery. |
| 401 | invalid_api_key | Missing, malformed, or revoked vm_live_ key. |
| 403 | project_suspended / organization_suspended | Project or organization is paused. Check your dashboard status. |
| 422 | domain_not_verified | The from domain is not verified on this project. |
| 422 | all_recipients_suppressed | All recipients previously hard-bounced, complained, or were suppressed. |
| 429 | limit_exceeded / rate_limited | Daily/monthly quota or per-second burst limit reached. |