Send email with NestJS

Quickstart#

1. Install the SDK

   bash

   npm install @poststack.dev/sdk @nestjs/config

2. Register the client in a module

   typescript

   // src/mail/mail.constants.ts
   export const POSTSTACK = Symbol('POSTSTACK');
   
   // src/mail/mail.module.ts
   import { Module } from '@nestjs/common';
   import { ConfigModule, ConfigService } from '@nestjs/config';
   import { PostStack } from '@poststack.dev/sdk';
   import { POSTSTACK } from './mail.constants';
   import { MailService } from './mail.service';
   
   @Module({
     imports: [ConfigModule],
     providers: [
       {
         provide: POSTSTACK,
         inject: [ConfigService],
         useFactory: (config: ConfigService) =>
           new PostStack(config.getOrThrow<string>('POSTSTACK_API_KEY')),
       },
       MailService,
     ],
     exports: [MailService],
   })
   export class MailModule {}

3. Send from a service

   typescript

   // src/mail/mail.service.ts
   import { Inject, Injectable } from '@nestjs/common';
   import { PostStack } from '@poststack.dev/sdk';
   import { POSTSTACK } from './mail.constants';
   
   @Injectable()
   export class MailService {
     constructor(@Inject(POSTSTACK) private readonly poststack: PostStack) {}
   
     async sendWelcome(to: string, name: string) {
       const { id } = await this.poststack.emails.send({
         from: 'Acme <hello@yourdomain.com>',   // must be on a verified domain
         to: [to],                              // always an array
         subject: `Welcome, ${name}`,
         html: `<h1>Welcome, ${name}!</h1>`,
         text: `Welcome, ${name}!`,
         tags: ['welcome'],
       });
       return id;                               // "em_..."
     }
   }
   
   // src/users/users.service.ts — inject it anywhere MailModule is imported
   import { Injectable } from '@nestjs/common';
   import { MailService } from '../mail/mail.service';
   
   @Injectable()
   export class UsersService {
     constructor(private readonly mail: MailService) {}
   
     async register(email: string, name: string) {
       // ...create the user
       await this.mail.sendWelcome(email, name);
     }
   }

4. Handle errors

   typescript

   // src/mail/poststack-exception.filter.ts
   import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus, Logger } from '@nestjs/common';
   import { PostStackError } from '@poststack.dev/sdk';
   import type { Response } from 'express';
   
   @Catch(PostStackError)
   export class PostStackExceptionFilter implements ExceptionFilter {
     private readonly logger = new Logger('PostStack');
   
     catch(err: PostStackError, host: ArgumentsHost) {
       this.logger.error(`${err.statusCode} ${err.message} (request ${err.requestId})`);
   
       // 400/422 are caused by the input (bad payload, unverified domain,
       // suppressed recipient); everything else is our problem, not the caller's.
       const status =
         err.statusCode === 400 || err.statusCode === 422
           ? err.statusCode
           : HttpStatus.BAD_GATEWAY;
   
       host.switchToHttp().getResponse<Response>().status(status).json({
         statusCode: status,
         message: status === HttpStatus.BAD_GATEWAY ? 'Email could not be sent' : err.message,
       });
     }
   }
   
   // main.ts
   app.useGlobalFilters(new PostStackExceptionFilter());

Send in the background with BullMQ#

Move sends out of the request with @nestjs/bullmq. Pass an idempotency_key derived from the job so a retried job never delivers twice — PostStack returns the original email instead.

// npm install @nestjs/bullmq bullmq
// mail.module.ts: imports: [BullModule.registerQueue({ name: 'mail' })]

// src/mail/mail.processor.ts
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Inject } from '@nestjs/common';
import { Job } from 'bullmq';
import { PostStack, PostStackError } from '@poststack.dev/sdk';
import { POSTSTACK } from './mail.constants';

@Processor('mail')
export class MailProcessor extends WorkerHost {
  constructor(@Inject(POSTSTACK) private readonly poststack: PostStack) {
    super();
  }

  async process(job: Job<{ to: string; name: string }>) {
    try {
      const { id } = await this.poststack.emails.send({
        from: 'Acme <hello@yourdomain.com>',
        to: [job.data.to],
        subject: `Welcome, ${job.data.name}`,
        html: `<h1>Welcome, ${job.data.name}!</h1>`,
        idempotency_key: `welcome-${job.id}`,
      });
      return { id };
    } catch (err) {
      // 400/422 will fail the same way on every attempt — don't retry them
      if (err instanceof PostStackError && [400, 422].includes(err.statusCode)) {
        await job.discard();
      }
      throw err;
    }
  }
}

// enqueue: await this.mailQueue.add('welcome', { to, name }, { attempts: 5, backoff: { type: 'exponential', delay: 30_000 } });

Attachments#

Attachments are base64 strings. With FileInterceptor the upload is already a Buffer. Limits: 10 attachments, 10 MB per file, 25 MB in total.

@Post('report')
@UseInterceptors(FileInterceptor('file'))
async sendReport(@UploadedFile() file: Express.Multer.File) {
  const { id } = await this.poststack.emails.send({
    from: 'reports@yourdomain.com',
    to: ['team@yourdomain.com'],
    subject: `Report: ${file.originalname}`,
    text: 'Report attached.',
    attachments: [
      {
        filename: file.originalname,
        content: file.buffer.toString('base64'),
        content_type: file.mimetype,
      },
    ],
  });
  return { id };
}

Replace the client in tests#

Override the POSTSTACK provider with a stub so unit tests never call the API.

const send = jest.fn().mockResolvedValue({ id: 'em_test' });

const moduleRef = await Test.createTestingModule({ imports: [MailModule] })
  .overrideProvider(POSTSTACK)
  .useValue({ emails: { send } })
  .compile();

await moduleRef.get(MailService).sendWelcome('ada@example.com', 'Ada');
expect(send).toHaveBeenCalledWith(expect.objectContaining({ to: ['ada@example.com'] }));

Framework integrations#

Common pitfalls#

FAQ#

Next steps