Developers

API v2 Documentation

Send email, validate addresses and manage contacts from your own applications.

API v2 documentation

The MailRush API is RESTful and uses JSON over HTTPS. Use it to send email, validate addresses and manage contacts from your own applications.

Base URL

https://app2.mailrush.io/api/v2

All requests must include your API key in the x-api-key header. Find your key in Settings → API Key.

Prefer to explore interactively? Run the collection in Postman.

Authentication

MailRush uses API key authentication. Include your private key in the x-api-key header on every request. All endpoints require HTTPS. Keep your key secret: anyone with it can send email from your organization.

Request headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Send email

Send a single email using an email account that belongs to your organization. Attachments are not supported in v2.

POST https://app2.mailrush.io/api/v2/email
FieldTypeRequiredNotes
fromEmail string (email) Yes Must be an active email account in your organization.
recipientEmail string (email) Yes Primary recipient.
subject string Yes Cannot be empty.
html string (HTML) Yes* Required if text is not provided.
text string Yes* Required if html is not provided. If omitted and html is present, a text version is generated automatically.
replyTo string (email) No Defaults to fromEmail. Any other address must first be verified in Settings → API Key → Reply-To addresses.

Constraints

  • subject is required.
  • Provide at least one of html or text. Send only text for a plain-text email with no HTML version.
  • Only the fields listed above are allowed. Other keys (for example cc, bcc or attachments) are rejected with 422.
  • If replyTo is not provided, fromEmail is used.
  • replyTo must be a single plain address (no display name). An address other than fromEmail must be verified for your organization by an owner or admin in Settings → API Key → Reply-To addresses; otherwise the request returns 422 and nothing is sent.
  • Replies sent to a replyTo address go directly to that mailbox and do not appear in the MailRush inbox, reply statistics or reply webhooks. Bounces are not affected.
  • Attachments are not accepted by this endpoint.
  • API emails are sent as provided: no open tracking, link tracking, footer or unsubscribe header is added. The From name is the name saved on the email account.
  • API rate limits: up to 10 API emails per minute and 100 per hour per organization (free trial: 2 per minute, 10 per hour, 10 per day and 30 per month). API emails also count toward your plan's daily and 30-day totals.
  • Per-sender limits: each fromEmail can send up to 100 emails per hour (MailRush mailboxes) or 200 per hour (connected external mailboxes), and up to your plan's daily limit per day. Campaigns, API, warmup and inbox replies from the same sender share these limits. When one is reached the request returns 429 with code SENDER_HOURLY_LIMIT or SENDER_DAILY_LIMIT, a Retry-After header (seconds) and a senderLimit object (window, limit, retryAt, retryAfterSeconds). Nothing is sent; retry after that time or use another sender.

Request example (cURL)

curl -X POST https://app2.mailrush.io/api/v2/email \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fromEmail": "notifications@yourdomain.com",
    "recipientEmail": "alice@example.com",
    "subject": "Welcome!",
    "html": "<h1>Hello</h1><p>Your account is ready.</p>"
  }'

Successful response

{ "success": true, "messageId": "<message-id@your-smtp>" }

Avoiding duplicate sends

Send an optional Idempotency-Key header (1 to 200 visible ASCII characters, for example your own send ID) with each email, and repeat the same key and body when you retry.

How retries behave

  • If that email was already accepted, the retry returns success: true with the original messageId and replayed: true, and nothing is sent again.
  • The same key with a different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Without a key, every request is a new email.
  • 409 EMAIL_SEND_OUTCOME_UNKNOWN means the email may or may not have been sent. Do not resend it automatically; check the Sent tab in MailRush.
  • 202 with recordingPending: true means the email was accepted but recording is not finished. Do not resend.

Validate email

Queue validation of one email address. The address is saved as a contact in your organization (or the existing contact is used), and the result is stored on that contact when validation finishes. The response confirms the request was queued; it does not contain the result.

POST https://app2.mailrush.io/api/v2/email/validate
FieldTypeRequiredNotes
email string (email) Yes The address to validate.

Rules

  • The body contains only email. Extra keys are rejected with 422.
  • An optional Idempotency-Key header makes retries safe.
  • Each request uses one validation from your plan's monthly allowance, then from purchased credits. When none are left the response is 429.

Request example (cURL)

curl -X POST https://app2.mailrush.io/api/v2/email/validate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "email": "maria.perez@example.com" }'

Successful response (202)

{
  "success": true,
  "status": "queued",
  "email": "maria.perez@example.com",
  "contact_id": 12345,
  "public_id": "4f9d2f0e3b1c4e21b6c2f8d1",
  "created_contact": false,
  "jobId": "..."
}

Create contact

Create a contact in your organization and assign it to a tag. If the tag does not exist, it is created. Duplicate emails are rejected.

POST https://app2.mailrush.io/api/v2/contacts
FieldTypeRequiredNotes
email string (email) Yes Unique per organization (non-deleted contacts).
first_name string No —
last_name string No —
title string No Honorific or role label.
company string No —
phone string No —
custom1..custom6 string No Free-form fields.
tag string No Defaults to untagged. A tag that does not exist is created.

Rules

  • Duplicate emails are rejected with 400.
  • Only the fields listed above are allowed. Extra keys cause 422 Unexpected fields.
  • When your plan's contact limit is reached, the contact is not created and the response is 403 with code: "CONTACT_LIMIT_REACHED" and the limit. Deleted contacts do not count.
  • A contact created with the tag of a running campaign enters that campaign's sequence automatically.

Request example (cURL)

curl -X POST https://app2.mailrush.io/api/v2/contacts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "maria.perez@example.com",
    "first_name": "Maria",
    "last_name": "Perez",
    "company": "Example Inc.",
    "tag": "customers"
  }'

Successful response (201)

{
  "success": true,
  "contact_id": 12345,
  "public_id": "4f9d2f0e3b1c4e21b6c2f8d1",
  "tag": "customers"
}

Unsubscribe contact

Unsubscribe a contact (opt-out) by email within your organization. The operation is idempotent: repeating it is safe.

POST https://app2.mailrush.io/api/v2/contacts/unsubscribe
FieldTypeRequiredNotes
email string (email) Yes Must exist in your organization.

Rules

  • Extra keys are rejected with 422.
  • An email that does not exist in your organization returns 404.
  • Unsubscribed contacts are skipped by campaigns. API emails are sent to the address you request, so check your own suppression data before calling the send endpoint.

Request example (cURL)

curl -X POST https://app2.mailrush.io/api/v2/contacts/unsubscribe \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "email": "jon@example.com" }'

Successful responses

{ "success": true, "message": "Unsubscribed successfully" }
{ "success": true, "message": "Already unsubscribed" }

Status codes

Status Label Description
200 OK Successful operation.
201 Created Resource created (for example, a contact).
202 Accepted Validation queued, or email accepted with recordingPending (do not resend).
400 Bad Request Business rule violation (for example, a duplicate contact email).
401 Unauthorized Invalid API key or inactive organization.
403 Forbidden Not allowed by business rules (for example, fromEmail not permitted, or CONTACT_LIMIT_REACHED).
404 Not Found Resource not found (for example, the contact to unsubscribe does not exist).
409 Conflict IDEMPOTENCY_KEY_CONFLICT (same key, different body) or EMAIL_SEND_OUTCOME_UNKNOWN (do not resend automatically).
422 Unprocessable Entity Validation failed (missing or invalid fields, unexpected keys).
429 Too Many Requests A limit was reached and nothing was sent. Sender limits return code SENDER_HOURLY_LIMIT or SENDER_DAILY_LIMIT with a Retry-After header; organization-wide limits return EMAIL_QUOTA_EXCEEDED. A sender blocked for the recipient's provider after a bounce reported spam, a blocklist or abuse returns SENDER_PROVIDER_BLOCKED with retryAt, a senderProviderBlock object and Retry-After. On the validate endpoint, no validations are left.
500 Server Error Internal or email provider error.

Send your first API email in minutes

Start your free trial, copy your API key from Settings and make your first request. No credit card required.

Start free trial API overview