Verify your domain
Add and verify your sending domain in the dashboard before production traffic.
API Documentation
Authenticate with API keys and send transactional email through POST /api/v1/message.
Create an API key
Generate an API key scoped to your verified domain and store it securely.
Send your first email
Call POST /api/v1/message with JSON and your Bearer token.
Use your API key as a Bearer token
Include your API key in the Authorization header on every request.
1
Authorization: Bearer <YOUR_API_KEY>
Official packages
- PHP (Laravel): mailsurge/laravel (compatible with Mailsurge)
POST /api/v1/message
Send JSON with a sender, recipients, and either HTML or text content. Requests must include application/json.
Endpoint
POST /api/v1/message
Base URL https://mailsurge.dev
Request body
from(string, required): Sender address, e.g. Sender Name <no-reply@yourdomain.com>.to(string|array, required): Recipient email or array of emails.subject(string, required): Message subject line.html(string, optional): HTML body.text(string, optional): Plain text body.cc(string|array, optional)bcc(string|array, optional)reply_to(string|array, optional)headers(object, optional): Custom headers, e.g. {"X-Campaign": "welcome"}.attachments(array, optional): Each item supports filename, content (base64 or raw text), content_type, disposition (attachment or inline), and content_id for inline images.
Responses
201 Createdon success with an empty body (message is queued for delivery).401 Unauthorizedwith{"reason": "Invalid key"}.402 Payment Requiredwhen the account has no active subscription.403 Forbiddenwhen the account is blocked or pending approval.400 Bad Requestwhen the from domain is invalid or not verified.413 Payload Too Largewhen attachments exceed 20MB or the queue payload exceeds 1MB.422 Unprocessable Entitywith validation errors for invalid input.429 Too Many Requestswhen new account sending limits are reached.
Notes
- Recipient fields accept a single email string or an array of emails.
- Provide at least one of
htmlortext. - Verify your sender domain before sending production traffic.
- For inline images, set
dispositiontoinline, provide acontent_id, and reference it in HTML as<img src="cid:your-content-id">.
1
curl -X POST "https://mailsurge.dev/api/v1/message" \
2
-H "Authorization: Bearer YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"from": "Sender <no-reply@yourdomain.com>",
6
"to": ["user@example.com"],
7
"subject": "Hello from Mailsurge",
8
"html": "<p>Hi there 👋</p>",
9
"text": "Hi there",
10
"headers": {
11
"X-Campaign": "welcome"
12
},
13
"attachments": [
14
{
15
"filename": "hello.txt",
16
"content": "SGVsbG8gd29ybGQh",
17
"content_type": "text/plain",
18
"disposition": "attachment"
19
}
20
]
21
}'
1
await fetch('https://mailsurge.dev/api/v1/message', {
2
method: 'POST',
3
headers: {
4
Authorization: 'Bearer ' + process.env.MAILSURGE_API_KEY,
5
'Content-Type': 'application/json',
6
},
7
body: JSON.stringify({
8
from: 'Sender <no-reply@yourdomain.com>',
9
to: ['user@example.com'],
10
subject: 'Hello from Mailsurge',
11
html: '<p>Hi there 👋</p>',
12
text: 'Hi there',
13
headers: {
14
'X-Campaign': 'welcome',
15
},
16
attachments: [
17
{
18
filename: 'hello.txt',
19
content: 'SGVsbG8gd29ybGQh',
20
content_type: 'text/plain',
21
disposition: 'attachment',
22
},
23
],
24
}),
25
});
1
Http::withToken(env('MAILSURGE_API_KEY'))
2
->post('https://mailsurge.dev/api/v1/message', [
3
'from' => 'Sender <no-reply@yourdomain.com>',
4
'to' => ['user@example.com'],
5
'subject' => 'Hello from Mailsurge',
6
'html' => '<p>Hi there 👋</p>',
7
'text' => 'Hi there',
8
'headers' => [
9
'X-Campaign' => 'welcome',
10
],
11
'attachments' => [
12
[
13
'filename' => 'hello.txt',
14
'content' => 'SGVsbG8gd29ybGQh',
15
'content_type' => 'text/plain',
16
'disposition' => 'attachment',
17
],
18
],
19
]);
Ship faster with guides
Pair this reference with deliverability guides and language quickstarts for production-ready integrations.