samurm / mail-backend

Mail backend with NestJS that uses mailgun and is ready to use other APIs.

Mail Server

Mail backend with NestJS that uses mailgun and is ready to use other APIs.

Description

This project is a mail backend using the mailgun API. It is made so that you can add different mail APIs thanks to the adapter design pattern. Next I will put how to install it and what are its routes with the format and type of data that has to be sent to the backend and what it returns to you.

Prerequisites

You need to have npm

npm

You need to have a mailgun account

mailgun

Installation

Create file .env with mailgun keys

PORT=3000
KEY=your-key
PUB_KEY=you-pub-key
DOMAIN=your-domain

$ npm install

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Routes

List /list

• Post /read

  • body = { "listName": "your-list-name" }

  • response = { "list": { "access_level": "", "address": "", "created_at": "", "description": "", "members_count": 0, "name": "" } }

• Post /member/create

  name, subscribed and vars are optionals

  • body = { "listName": "your-list-name", "member": { "name": "Bob", "subscribed": true, "address": "[e-mail]", "vars": { "example": 0 } } }

  • response = { "member": { "address": "[e-mail]", "name": "Bob", "subscribed": true, "vars": { "example": 0 } }, "message": "Mailing list member has been created" }

• Post /members/create

  name, subscribed and vars are optionals

  • body = { "listName": "your-list-name", "members": [ { "name": "Bob", "address": "[e-mail]", "vars": { "example": 0 } }, { "name": "Bob2", "address": "[e-mail]", "vars": { "age": 1 } } ], "subscribed": true }

  • response = { "list": { "access_level": "readonly", "address": "your-list-name", "created_at": "", "description": "", "members_count": 2, "name": "" }, "message": "Mailing list has been updated", "task-id": "" }

• Post /members

  • body = { "listName": "your-list-name" }

  • response = { "items": [ { "address": "[e-mail]", "name": "Bob", "subscribed": true, "vars": { "example": 0 } }, { "address": "[e-mail]", "name": "Bob2", "subscribed": true, "vars": { "age": 1 } }], "total_count": 9 }

• Put /members

  updateMember can contain name, address, subscribed or vars

  • body = { "listName": "your-list-name", "member": "[e-mail]", "updateMember": { "address": "[e-mail]" } }

  • response = { "member": { "address": "[e-mail]", "name": "Bob", "subscribed": true, "vars": { "age": 22 } }, "message": "Mailing list member has been updated" }

• Delete /member

  • body = { "listName": "your-list-name", "member": "[e-mail]" }

  • response = { "member": { "address": "[e-mail]" }, "message": "Mailing list member has been deleted" }

Mail /mail

• Post /send/individual

  You can send plane text, html or a name of a template of your API.

  Then you can send variables in your html with 'recipient-variables' or send variables in your template with 'h:X-Mailgun-Variables'.

  text, html, template, 'recipient-variables', 'h:X-Mailgun-Variables', attachment are optionals.

  Example 1

  • body = { "from": "[e-mail]", "to": "[e-mail]", "subject": "hi", "text": "This is a message" }

  Example 2

  • body = { "from": "[e-mail]", "to": "[e-mail]", "subject": "hi", "recipient-variables": { "[e-mail]" : {"id": "ABC123456789"} }, "html": "%recipient.id%", "attachment": "name-file" }

  Example 3

  • body = { "from": "[e-mail]", "to": "[e-mail]", "subject": "hi", "h:X-Mailgun-Variables": '{"body": "This is a message"}', "template": "name-template", "attachment": "name-file" }

  • response = { "id": "", "message": "Queued. Thank you." }

• Post /send/multiple

  You have the same format as /send/individual, and u can add bcc or cc as array.

  Example 1

  • body = { "from": "[e-mail]", "to": "[e-mail]", "cc": ["[e-mail]", "[e-mail]"], "subject": "hi", "recipient-variables": { "[e-mail]" : {"id": "ABC123456789"}, "[e-mail]" : {"id": "987654321CBA"} }, "html": "%recipient.id%", "attachment": "name-file" }

  Example 2

  • body = { "from": "[e-mail]", "to": "[e-mail]", "bcc": ["[e-mail]", "[e-mail]"], "subject": "hi", "recipient-variables": { "[e-mail]" : {"id": "ABC123456789"}, "[e-mail]" : {"id": "987654321CBA"} }, "html": "%recipient.id%", "attachment": "name-file" }

  • response = { "id": "", "message": "Queued. Thank you." }

• Post /send/validate

  • body = { "mail": "[e-mail]" }

  • response = { "address": "[e-mail]", "did_you_mean": null, "is_disposable_address": false, "is_role_address": false, "is_valid": true, "mailbox_verification": "true", "parts": { "display_name": null, "domain": "gmail.com", "local_part": "bob" }, "reason": null }

Upload Files /

• Post /upload

  • body = { "file" : file }

  • response = { "success": true }

Built With

• NestJS - The web framework used.
• Mailgun - API Mail.