MassMailer REST API
Professional email campaign API. All endpoints return JSON. Auth via Laravel Sanctum Bearer tokens.
Base URL: http://excel.local/api/v1
Laravel
Sanctum
Rate Limited
🔑 How to Authenticate
Step 1 — Login
POST /auth/login
{"email":"admin@mail.com","password":"password"}
// Response → {"data":{"token":"1|abc..."}}
Step 2 — Send token in every request
Authorization: Bearer 1|abc... Accept: application/json
🔐 Authentication
POST/auth/loginGet Bearer token▼
Request Body
| Field | Type | |
|---|---|---|
| string | required | |
| password | string | required |
Response 200
{"success":true,"data":{"id":1,"name":"Admin","email":"admin@mail.com","token":"1|abc..."}}
POST/auth/registerRegister new user▼
Request Body
| Field | Type | |
|---|---|---|
| name | string | required |
| string | required | |
| password | string | required |
| password_confirmation | string | required |
POST/auth/logoutRevoke current token▼
🔒 Bearer Token Required
📮 SMTP Senders
GET/smtps?search=&per_page=15▼
🔒 Bearer Token Required
POST/smtpsCreate SMTP▼
🔒 Bearer Token Required
Request Body
| Field | Type | Example | |
|---|---|---|---|
| display_name | string | required | Newsletter |
| smtp_host | string | required | smtp.gmail.com |
| port | integer | required | 587 |
| username | string | required | sender@gmail.com |
| password | string | required | apppassword |
| encryption | tls|ssl|none | optional | tls |
| daily_limit | integer | optional | 1990 |
| hourly_limit | integer | optional | 490 |
GET/smtps/{id}▼
🔒 Bearer Token Required
PUT/smtps/{id}All fields
optional▼
🔒 Bearer Token Required
DEL/smtps/{id}▼
🔒 Bearer Token Required
POST/smtps/testSend test email▼
🔒 Bearer Token Required
Body
{"smtp_id":1,"recipient_email":"test@mail.com"}
POST/smtps/{id}/duplicateClone
entry▼
🔒 Bearer Token Required
👤 Senders
GET/senders▼
🔒 Bearer Token Required
POST/sendersCreate sender▼
🔒 Bearer Token Required
Body
{"name":"Ahmed","email":"ahmed@mail.com","password":"pass","phone":"+201001234567"}
GET/senders/{id}▼
🔒 Bearer Token Required
PUT/senders/{id}▼
🔒 Bearer Token Required
DEL/senders/{id}▼
🔒 Bearer Token Required
📧 Messages
GET/messages▼
🔒 Bearer Token Required
POST/messagesSend Now OR Schedule▼
🔒 Bearer Token Required
Send Now (mode: "now")
{"subject":"Campaign","content":"<h1>Hello!</h1>","smtp_sender_id":[1,2],"data_excel_id":[1,2,3],"mode":"now"}
Schedule (mode: "schedule")
{"subject":"Campaign","content":"<h1>Hello!</h1>","smtp_sender_id":[1],"data_excel_id":[1,2,3],"mode":"schedule","start_at":"2024-06-01 09:00:00","duration_value":3,"duration_unit":"days","label":"Summer"}
duration_unit: minutes · hours · days · weeks
Response 201
{"success":true,"message":"Emails are being dispatched.","total_queued":1980,"skipped":20}
GET/messages/{id}▼
🔒 Bearer Token Required
PUT/messages/{id}Update
subject/label▼
🔒 Bearer Token Required
Body
{"subject":"New Subject","label":"My Campaign"}
DEL/messages/{id}▼
🔒 Bearer Token Required
GET/messages/receivers?category_ids[]=1▼
🔒 Bearer Token Required
POST/messages/calculate-duration▼
🔒 Bearer Token Required
Body
{"sender_count":3,"receiver_count":10000}
// Response → {"data":{"value":2,"unit":"days"}}
POST/messages/queue/{id}/pause▼
🔒 Bearer Token Required
POST/messages/queue/{id}/resume▼
🔒 Bearer Token Required
POST/messages/queue/{id}/cancel▼
🔒 Bearer Token Required
GET/messages/{id}/schedule▼
🔒 Bearer Token Required
POST/messages/{id}/schedule/cancel▼
🔒 Bearer Token Required
POST/messages/reset-statussent → pending▼
🔒 Bearer Token Required
POST/messages/reset-failedfailed → pending▼
🔒 Bearer Token Required
📋 Contacts
GET/contacts▼
🔒 Bearer Token Required
POST/contactsBulk create from phone list▼
🔒 Bearer Token Required
Body
{"phones":"+201001234567\n+201009876543","names":"Ali\nMohamed","group_id":1}
Response 201
{"data":{"summary":{"saved_count":2,"duplicate_count":0,"invalid_count":0}}}
GET/contacts/search?query=ahmed▼
🔒 Bearer Token Required
POST/contacts/excelImport xlsx/csv (multipart)▼
🔒 Bearer Token Required
Form Data (multipart/form-data)
| Field | Type |
|---|---|
| file | file (xlsx/csv) |
| group_id | integer |
DEL/contacts/bulkBulk delete by IDs▼
🔒 Bearer Token Required
Body
{"ids":[1,2,3,4]}
GET/contacts/{id}▼
🔒 Bearer Token Required
PUT/contacts/{id}▼
🔒 Bearer Token Required
DEL/contacts/{id}▼
🔒 Bearer Token Required
👥 Groups
GET/groups▼
🔒 Bearer Token Required
POST/groupsCreate group▼
🔒 Bearer Token Required
Body
{"name":"VIP Clients","description":"High value customers"}
GET/groups/{id}▼
🔒 Bearer Token Required
PUT/groups/{id}▼
🔒 Bearer Token Required
DEL/groups/{id}▼
🔒 Bearer Token Required
GET/groups/{id}/contactsContacts in this
group▼
🔒 Bearer Token Required
⚙️ Settings
GET/settingsGet all grouped settings▼
🔒 Bearer Token Required
POST/settingsUpdate settings▼
🔒 Bearer Token Required
Body
{"daily_limit":1990,"hourly_limit":490,"batch_size":200}
📝 Templates
GET/templates▼
🔒 Bearer Token Required
POST/templatesCreate template▼
🔒 Bearer Token Required
Body
{"name":"Welcome Email","subject":"Welcome!","content":"<h1>Hello!</h1>"}
GET/templates/{id}▼
🔒 Bearer Token Required
PUT/templates/{id}▼
🔒 Bearer Token Required
DEL/templates/{id}▼
🔒 Bearer Token Required
❌ Error Codes
| Code | Meaning | When |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | Resource created |
| 401 | Unauthenticated | Missing / invalid token |
| 403 | Forbidden | Not authorized |
| 404 | Not Found | Route / resource missing |
| 422 | Validation Error | Invalid input fields |
| 429 | Too Many Requests | Rate limit hit |
| 500 | Server Error | Unexpected error |
Standard Error Response
{"success":false,"message":"Validation failed.","errors":{"email":["The email field is required."]}}