Marshmellos

API Reference

The Marshmellos API is a REST API that uses JSON for request and response bodies.

Base URL

https://api.marshmellos.com/v1

Authentication

All API requests require an API key in the Authorization header.

Example request
curl -X POST https://api.marshmellos.com/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", ...}'

Generate API keys in your dashboard settings.

Endpoints

POST/send

Send Email

Send a transactional email immediately

Request body
{
  "to": "[email protected]",
  "from": "[email protected]",
  "subject": "Welcome to our app",
  "html": "<h1>Hello!</h1><p>Thanks for signing up.</p>",
  "text": "Hello! Thanks for signing up."
}
Response
{
  "id": "msg_01H8EXAMPLE",
  "status": "sent",
  "to": "[email protected]",
  "created_at": "2024-01-15T10:30:00Z"
}
POST/send/template

Send with Template

Send an email using a pre-defined template

Request body
{
  "to": "[email protected]",
  "template_id": "tmpl_welcome",
  "variables": {
    "name": "Alex",
    "company": "Acme Inc"
  }
}
Response
{
  "id": "msg_01H8EXAMPLE",
  "status": "sent",
  "template_id": "tmpl_welcome",
  "created_at": "2024-01-15T10:30:00Z"
}
GET/emails/{id}

Get Email

Retrieve details and events for a specific email

Response
{
  "id": "msg_01H8EXAMPLE",
  "status": "delivered",
  "to": "[email protected]",
  "subject": "Welcome to our app",
  "events": [
    { "type": "sent", "timestamp": "2024-01-15T10:30:00Z" },
    { "type": "delivered", "timestamp": "2024-01-15T10:30:02Z" },
    { "type": "opened", "timestamp": "2024-01-15T10:35:12Z" }
  ]
}
GET/emails

List Emails

List all emails with optional filters

Response
{
  "data": [
    { "id": "msg_01H8ABC", "to": "[email protected]", "status": "delivered" },
    { "id": "msg_01H8DEF", "to": "[email protected]", "status": "sent" }
  ],
  "has_more": true,
  "cursor": "cur_01H8NEXT"
}
POST/templates

Create Template

Create a reusable email template

Request body
{
  "name": "Welcome Email",
  "subject": "Welcome, {{name}}!",
  "html": "<h1>Hi {{name}}</h1><p>Welcome to {{company}}.</p>",
  "text": "Hi {{name}}, welcome to {{company}}."
}
Response
{
  "id": "tmpl_01H8EXAMPLE",
  "name": "Welcome Email",
  "created_at": "2024-01-15T10:30:00Z"
}
POST/domains

Add Domain

Add a new sending domain for verification

Request body
{
  "domain": "mail.yourdomain.com"
}
Response
{
  "id": "dom_01H8EXAMPLE",
  "domain": "mail.yourdomain.com",
  "status": "pending",
  "dns_records": [
    { "type": "TXT", "host": "_dmarc", "value": "v=DMARC1; p=none" },
    { "type": "CNAME", "host": "s1._domainkey", "value": "..." }
  ]
}
POST/webhooks

Create Webhook

Register a webhook endpoint for email events

Request body
{
  "url": "https://yourapp.com/webhooks/email",
  "events": ["delivered", "bounced", "opened", "clicked"]
}
Response
{
  "id": "whk_01H8EXAMPLE",
  "url": "https://yourapp.com/webhooks/email",
  "events": ["delivered", "bounced", "opened", "clicked"],
  "secret": "whsec_..."
}

Error Codes

The API uses standard HTTP status codes. Here are the most common:

CodeNameDescription
400Bad RequestInvalid request body or parameters
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key doesn't have required permissions
404Not FoundResource not found
429Rate LimitedToo many requests, slow down
500Server ErrorSomething went wrong on our end

Rate Limits

API requests are rate limited based on your plan:

  • Free: 100 requests per minute
  • Pro: 1,000 requests per minute
  • Enterprise: Custom limits

Rate limit headers are included in every response:

Rate limit headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 1705312200

SDKs & Libraries

Use our official SDKs for faster integration:

Node.jsPythonRubyGo