Elastic Email Angular SDK

The official Angular client library for the Elastic Email REST API v4, built on Angular's HttpClient and RxJS.

Installation • Quick start • Examples • API reference • Models • Contributing

Features

Transactional and bulk email. Send single messages, bulk campaigns or CSV merge-file sends.
Safe retries. Add an optional Idempotency-Key to a send so a retried request never delivers the same email twice.
Contacts, lists and segments. Add, update, import, export and bulk-delete contacts.
Campaigns and automations. Create, update, pause and trigger automations for a contact.
Templates, files and attachments. Manage templates and uploaded files.
Domains. Verify sending domains and check SPF, DKIM, tracking and certificate status.
Webhooks and inbound routes. Receive delivery events, optionally signed with HMAC-SHA256 and sent as JSON, and route incoming mail.
Statistics, events and suppressions. Track delivery, bounces, complaints and unsubscribes.
Subaccounts and security. Manage subaccounts and API keys.
Angular-native. Every API class is an injectable service (providedIn: 'root') built on HttpClient. Methods return RxJS Observables, and every request and response has a TypeScript type.

Requirements

Platform	Version
Angular	19 (`@angular/core` and `@angular/common` `^19.0.0`)
RxJS	`^7.4.0`
TypeScript	`>=5.5.0 <5.7.0`

You'll also need an Elastic Email API key. You can create one in your API settings. Each endpoint's documentation lists the access level it needs.

Installation

Install the @elasticemail/elasticemail-client-ts-angular package from npm:

npm install @elasticemail/elasticemail-client-ts-angular

Or with yarn or pnpm:

yarn add @elasticemail/elasticemail-client-ts-angular
pnpm add @elasticemail/elasticemail-client-ts-angular

Angular and RxJS are peer dependencies, so the SDK uses the versions your app already has. The package is built with ng-packagr in the Angular Package Format, so there's nothing to compile.

Quick start

Important

Elastic Email only sends from verified domains. Before your first send, verify your sending domain and use an address on that domain as the sender.

Important

Never ship your API key to a browser. Anything in your Angular bundle can be read by anyone who loads the page. Use the SDK with a key only in server-side code (for example Angular SSR), or point the browser build at your own backend, which adds the key. See Call through your own backend.

Configure the client

Provide HttpClient and a Configuration with your API key. With Angular SSR, put the key in the server config (app.config.server.ts) so it never reaches the browser bundle:

// app.config.server.ts
import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { Configuration } from '@elasticemail/elasticemail-client-ts-angular';
import { appConfig } from './app.config';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    {
      provide: Configuration,
      useFactory: () => new Configuration({
        credentials: { apikey: () => process.env['ELASTICEMAIL_API_KEY'] },
      }),
    },
  ],
};

export const config = mergeApplicationConfig(appConfig, serverConfig);

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withFetch } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withFetch())],
};

The API services (EmailsService, ContactsService…) are providedIn: 'root', so you inject them directly. You don't need to import ApiModule.

Tip

Keep your API key out of source code. Load it from an environment variable, a .env file that isn't committed, or a secrets manager.

Send a transactional email

import { Injectable, inject } from '@angular/core';
import { HttpErrorResponse } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import {
  BodyContentType,
  EmailsService,
  EmailTransactionalMessageData,
} from '@elasticemail/elasticemail-client-ts-angular';

@Injectable({ providedIn: 'root' })
export class WelcomeMailer {
  private readonly emails = inject(EmailsService);

  async sendWelcome(to: string): Promise<void> {
    const message: EmailTransactionalMessageData = {
      Recipients: {
        To: [to],
      },
      Content: {
        From: 'My App <no-reply@yourdomain.com>',
        Subject: 'Welcome aboard!',
        Body: [
          { ContentType: BodyContentType.Html, Content: '<h1>Hello!</h1><p>Thanks for signing up.</p>' },
          { ContentType: BodyContentType.PlainText, Content: 'Hello! Thanks for signing up.' },
        ],
      },
    };

    try {
      const result = await firstValueFrom(this.emails.emailsTransactionalPost(message));
      console.log(`Sent. TransactionID: ${result.TransactionID}, MessageID: ${result.MessageID}`);
    } catch (error) {
      if (error instanceof HttpErrorResponse) {
        console.error(`Elastic Email API error ${error.status}:`, error.error);
      } else {
        throw error;
      }
    }
  }
}

The From address must use a domain you've verified in your Elastic Email account.

Note

Each method returns a cold Observable: nothing is sent until you subscribe (or call firstValueFrom). By default it emits the response body. Pass 'response' as the observe argument to get the full HttpResponse, or 'events' for progress events. Field names match the API's PascalCase names (Recipients, Content, TransactionID…).

Retry a send safely (Idempotency-Key)

Pass an idempotency key with a send so that retrying after a timeout or a dropped connection can't deliver the email twice. If the same key comes back with the same body within 24 hours, the API returns the stored response (same TransactionID, plus an Idempotency-Replayed: true header) instead of sending again. Generate a new key for every send and reuse it only to retry that send with an identical body: a different body gets 422, a retry while the first request is still running gets 409, and 503 means the key couldn't be checked, so retry later with the same key. Sends without a key work as before.

const idempotencyKey = crypto.randomUUID(); // one key per send, reused only for its retries

// On a timeout, network error or 503, send again with the same message and the same key.
const response = await firstValueFrom(
  this.emails.emailsTransactionalPost(message, idempotencyKey, 'response'),
);
const replayed = response.headers.get('Idempotency-Replayed') === 'true';
console.log(`TransactionID: ${response.body?.TransactionID}${replayed ? ' (replayed)' : ''}`);

The key is the optional second argument of emailsTransactionalPost, emailsPost and emailsMergefilePost, so observe comes third. Calls written for earlier versions, such as emailsTransactionalPost(message, 'response'), still work.

Send from a template with merge fields

this.emails.emailsTransactionalPost({
  Recipients: { To: ['john.doe@example.com'] },
  Content: {
    From: 'My App <no-reply@yourdomain.com>',
    TemplateName: 'welcome-template',
    Merge: { firstname: 'John' },
  },
}).subscribe(result => console.log(result.TransactionID));

Call through your own backend

In a browser build, leave the key out and set basePath to an endpoint on your own server that adds the X-ElasticEmail-ApiKey header and forwards the request to https://api.elasticemail.com/v4:

// app.config.ts (browser)
import { Configuration } from '@elasticemail/elasticemail-client-ts-angular';

providers: [
  provideHttpClient(withFetch()),
  { provide: Configuration, useValue: new Configuration({ basePath: '/api/elasticemail' }) },
],

You can also provide the base path on its own with the BASE_PATH injection token: { provide: BASE_PATH, useValue: '/api/elasticemail' }.

Timeouts and headers

Requests go through Angular's HttpClient, so use an interceptor for headers, timeouts or retries on every call:

import { HttpInterceptorFn, provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
import { timeout } from 'rxjs';

const elasticEmailInterceptor: HttpInterceptorFn = (req, next) =>
  next(req.clone({ setHeaders: { 'X-My-Header': 'x' } })).pipe(timeout(30000)); // ms

providers: [provideHttpClient(withFetch(), withInterceptors([elasticEmailInterceptor]))],

For a single call, pipe RxJS operators onto the returned Observable, e.g. this.emails.emailsTransactionalPost(message).pipe(timeout(30000)).

Using ApiModule in an NgModule app

import { NgModule } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { ApiModule, Configuration } from '@elasticemail/elasticemail-client-ts-angular';

export function apiConfigFactory(): Configuration {
  return new Configuration({ basePath: '/api/elasticemail' });
}

@NgModule({
  imports: [ApiModule.forRoot(apiConfigFactory)],
  providers: [provideHttpClient()],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
})
export class AppModule {}

Import ApiModule once, in your root module only. Importing it a second time throws ApiModule is already loaded.

Customizing path parameter encoding

By default only path parameters of style simple, and dates in date-time format, are encoded. Every Elastic Email path parameter uses the simple style, so most apps don't need to change this. To use your own encoder, pass encodeParam to the Configuration:

import { Configuration, Param } from '@elasticemail/elasticemail-client-ts-angular';

new Configuration({
  encodeParam: (param: Param) => myParamEncoder(param),
});

Create a signed webhook

Webhooks can sign every request with HMAC-SHA256 and send events as a POST with a JSON body. Both options are set when you create the webhook and can't be changed later. Webhooks created without them keep working as unsigned GET requests.

import { inject } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { WebhookDeliveryMethod, WebhookService } from '@elasticemail/elasticemail-client-ts-angular';

// Server-side only (e.g. Angular SSR): the secret must never reach the browser.
const webhooks = inject(WebhookService);

const webhook = await firstValueFrom(webhooks.webhookPost({
  Name: 'my-webhook',
  URL: 'https://your-app.example.com/webhook',
  NotificationForSent: true,
  NotificationForOpened: true,
  NotificationForClicked: true,
  EnableSigning: true,
  DeliveryMethod: WebhookDeliveryMethod.PostJson,
}));

// Returned only now: store it, e.g. as ELASTICEMAIL_WEBHOOK_SECRET.
console.log('Signing secret:', webhook.SigningSecret);

SigningSecret is returned only when the webhook is created and when you rotate it with webhookByPublicidSecretRotatePost, so store it right away. Each signed request carries X-ElasticEmail-Timestamp and X-ElasticEmail-Signature: v1=<hex>, where the signature is hex(HMAC-SHA256(secret, "{timestamp}\n{METHOD}\n{path and query}\n{raw body}")). Verify it against the raw body before you parse the JSON, reject timestamps more than 5 minutes old, and compare in constant time. The webhooks guide and the examples repository have ready-made handlers.

More examples

More complete, runnable samples are in the Elastic Email examples repository. It covers transactional email, SMTP, webhooks, inbound email, contacts and serverless platforms across 20+ languages and frameworks.

🟢 Node.js examples (server-side TypeScript, for the backend your Angular app calls)
📂 All examples

Authentication

Scheme	Header	Used for
`apikey`	`X-ElasticEmail-ApiKey`	All API calls. Set it with `new Configuration({ credentials: { apikey } })`

API limits

Up to 20 concurrent connections per account
A hard timeout of 600 seconds per request

API reference

All URIs are relative to https://api.elasticemail.com/v4. The SDK covers 115 endpoints across 16 injectable services: CampaignsService, ContactsService, DomainsService, EmailsService, EventsService, FilesService, InboundRouteService, ListsService, SecurityService, SegmentsService, StatisticsService, SubAccountsService, SuppressionsService, TemplatesService, VerificationsService and WebhookService.

Show all endpoints

Class	Method	HTTP request	Description
CampaignsService	campaignsAutomationByNameTriggerPost	POST /campaigns/automation/{name}/trigger	Trigger Automation for Contact
CampaignsService	campaignsByNameDelete	DELETE /campaigns/{name}	Delete Campaign
CampaignsService	campaignsByNameGet	GET /campaigns/{name}	Load Campaign
CampaignsService	campaignsByNamePausePut	PUT /campaigns/{name}/pause	Pause Campaign
CampaignsService	campaignsByNamePut	PUT /campaigns/{name}	Update Campaign
CampaignsService	campaignsGet	GET /campaigns	Load Campaigns
CampaignsService	campaignsPost	POST /campaigns	Add Campaign
ContactsService	contactsByEmailDelete	DELETE /contacts/{email}	Delete Contact
ContactsService	contactsByEmailGet	GET /contacts/{email}	Load Contact
ContactsService	contactsByEmailPut	PUT /contacts/{email}	Update Contact
ContactsService	contactsDeletePost	POST /contacts/delete	Delete Contacts Bulk
ContactsService	contactsExportByIdStatusGet	GET /contacts/export/{id}/status	Check Export Status
ContactsService	contactsExportPost	POST /contacts/export	Export Contacts
ContactsService	contactsGet	GET /contacts	Load Contacts
ContactsService	contactsImportPost	POST /contacts/import	Upload Contacts
ContactsService	contactsPost	POST /contacts	Add Contact
DomainsService	domainsByDomainDelete	DELETE /domains/{domain}	Delete Domain
DomainsService	domainsByDomainGet	GET /domains/{domain}	Load Domain
DomainsService	domainsByDomainPut	PUT /domains/{domain}	Update Domain
DomainsService	domainsByDomainRestrictedGet	GET /domains/{domain}/restricted	Check for domain restriction
DomainsService	domainsByDomainVerificationPut	PUT /domains/{domain}/verification	Verify Domain
DomainsService	domainsByEmailDefaultPatch	PATCH /domains/{email}/default	Set Default
DomainsService	domainsGet	GET /domains	Load Domains
DomainsService	domainsPost	POST /domains	Add Domain
EmailsService	emailsByMsgidViewGet	GET /emails/{msgid}/view	View Email
EmailsService	emailsByTransactionidStatusGet	GET /emails/{transactionid}/status	Get Status
EmailsService	emailsMergefilePost	POST /emails/mergefile	Send Bulk Emails CSV
EmailsService	emailsPost	POST /emails	Send Bulk Emails
EmailsService	emailsTransactionalPost	POST /emails/transactional	Send Transactional Email
EventsService	eventsByTransactionidGet	GET /events/{transactionid}	Load Email Events
EventsService	eventsChannelsByNameExportPost	POST /events/channels/{name}/export	Export Channel Events
EventsService	eventsChannelsByNameGet	GET /events/channels/{name}	Load Channel Events
EventsService	eventsChannelsExportByIdStatusGet	GET /events/channels/export/{id}/status	Check Channel Export Status
EventsService	eventsExportByIdStatusGet	GET /events/export/{id}/status	Check Export Status
EventsService	eventsExportPost	POST /events/export	Export Events
EventsService	eventsGet	GET /events	Load Events
FilesService	filesByNameDelete	DELETE /files/{name}	Delete File
FilesService	filesByNameGet	GET /files/{name}	Download File
FilesService	filesByNameInfoGet	GET /files/{name}/info	Load File Details
FilesService	filesGet	GET /files	List Files
FilesService	filesPost	POST /files	Upload File
InboundRouteService	inboundrouteByIdDelete	DELETE /inboundroute/{id}	Delete Route
InboundRouteService	inboundrouteByIdGet	GET /inboundroute/{id}	Get Route
InboundRouteService	inboundrouteByIdPut	PUT /inboundroute/{id}	Update Route
InboundRouteService	inboundrouteGet	GET /inboundroute	Get Routes
InboundRouteService	inboundrouteOrderPut	PUT /inboundroute/order	Update Sorting
InboundRouteService	inboundroutePost	POST /inboundroute	Create Route
ListsService	listsByListnameContactsGet	GET /lists/{listname}/contacts	Load Contacts in List
ListsService	listsByNameContactsPost	POST /lists/{name}/contacts	Add Contacts to List
ListsService	listsByNameContactsRemovePost	POST /lists/{name}/contacts/remove	Remove Contacts from List
ListsService	listsByNameDelete	DELETE /lists/{name}	Delete List
ListsService	listsByNameGet	GET /lists/{name}	Load List
ListsService	listsByNamePut	PUT /lists/{name}	Update List
ListsService	listsGet	GET /lists	Load Lists
ListsService	listsPost	POST /lists	Add List
SecurityService	securityApikeysByNameDelete	DELETE /security/apikeys/{name}	Delete ApiKey
SecurityService	securityApikeysByNameGet	GET /security/apikeys/{name}	Load ApiKey
SecurityService	securityApikeysByNamePut	PUT /security/apikeys/{name}	Update ApiKey
SecurityService	securityApikeysGet	GET /security/apikeys	List ApiKeys
SecurityService	securityApikeysPost	POST /security/apikeys	Add ApiKey
SecurityService	securitySmtpByNameDelete	DELETE /security/smtp/{name}	Delete SMTP Credential
SecurityService	securitySmtpByNameGet	GET /security/smtp/{name}	Load SMTP Credential
SecurityService	securitySmtpByNamePut	PUT /security/smtp/{name}	Update SMTP Credential
SecurityService	securitySmtpGet	GET /security/smtp	List SMTP Credentials
SecurityService	securitySmtpPost	POST /security/smtp	Add SMTP Credential
SegmentsService	segmentsByNameDelete	DELETE /segments/{name}	Delete Segment
SegmentsService	segmentsByNameGet	GET /segments/{name}	Load Segment
SegmentsService	segmentsByNamePut	PUT /segments/{name}	Update Segment
SegmentsService	segmentsGet	GET /segments	Load Segments
SegmentsService	segmentsPost	POST /segments	Add Segment
StatisticsService	statisticsCampaignsByNameGet	GET /statistics/campaigns/{name}	Load Campaign Stats
StatisticsService	statisticsCampaignsGet	GET /statistics/campaigns	Load Campaigns Stats
StatisticsService	statisticsChannelsByNameGet	GET /statistics/channels/{name}	Load Channel Stats
StatisticsService	statisticsChannelsGet	GET /statistics/channels	Load Channels Stats
StatisticsService	statisticsGet	GET /statistics	Load Statistics
SubAccountsService	subaccountsByEmailApikeyGet	GET /subaccounts/{email}/apikey	Get SubAccount ApiKey
SubAccountsService	subaccountsByEmailCreditsPatch	PATCH /subaccounts/{email}/credits	Add, Subtract Email Credits
SubAccountsService	subaccountsByEmailDelete	DELETE /subaccounts/{email}	Delete SubAccount
SubAccountsService	subaccountsByEmailGet	GET /subaccounts/{email}	Load SubAccount
SubAccountsService	subaccountsByEmailSettingsEmailPut	PUT /subaccounts/{email}/settings/email	Update SubAccount Email Settings
SubAccountsService	subaccountsGet	GET /subaccounts	Load SubAccounts
SubAccountsService	subaccountsPost	POST /subaccounts	Add SubAccount
SuppressionsService	suppressionsBouncesGet	GET /suppressions/bounces	Get Bounce List
SuppressionsService	suppressionsBouncesImportPost	POST /suppressions/bounces/import	Add Bounces Async
SuppressionsService	suppressionsBouncesPost	POST /suppressions/bounces	Add Bounces
SuppressionsService	suppressionsByEmailDelete	DELETE /suppressions/{email}	Delete Suppression
SuppressionsService	suppressionsByEmailGet	GET /suppressions/{email}	Get Suppression
SuppressionsService	suppressionsComplaintsGet	GET /suppressions/complaints	Get Complaints List
SuppressionsService	suppressionsComplaintsImportPost	POST /suppressions/complaints/import	Add Complaints Async
SuppressionsService	suppressionsComplaintsPost	POST /suppressions/complaints	Add Complaints
SuppressionsService	suppressionsGet	GET /suppressions	Get Suppressions
SuppressionsService	suppressionsUnsubscribesGet	GET /suppressions/unsubscribes	Get Unsubscribes List
SuppressionsService	suppressionsUnsubscribesImportPost	POST /suppressions/unsubscribes/import	Add Unsubscribes Async
SuppressionsService	suppressionsUnsubscribesPost	POST /suppressions/unsubscribes	Add Unsubscribes
TemplatesService	templatesByNameDelete	DELETE /templates/{name}	Delete Template
TemplatesService	templatesByNameGet	GET /templates/{name}	Load Template
TemplatesService	templatesByNamePut	PUT /templates/{name}	Update Template
TemplatesService	templatesGet	GET /templates	Load Templates
TemplatesService	templatesPost	POST /templates	Add Template
VerificationsService	verificationsByEmailDelete	DELETE /verifications/{email}	Delete Email Verification Result
VerificationsService	verificationsByEmailGet	GET /verifications/{email}	Get Email Verification Result
VerificationsService	verificationsByEmailPost	POST /verifications/{email}	Verify Email
VerificationsService	verificationsFilesByIdDelete	DELETE /verifications/files/{id}	Delete File Verification Result
VerificationsService	verificationsFilesByIdResultDownloadGet	GET /verifications/files/{id}/result/download	Download File Verification Result
VerificationsService	verificationsFilesByIdResultGet	GET /verifications/files/{id}/result	Get Detailed File Verification Result
VerificationsService	verificationsFilesByIdVerificationPost	POST /verifications/files/{id}/verification	Start verification
VerificationsService	verificationsFilesPost	POST /verifications/files	Upload File with Emails
VerificationsService	verificationsFilesResultGet	GET /verifications/files/result	Get Files Verification Results
VerificationsService	verificationsGet	GET /verifications	Get Emails Verification Results
WebhookService	webhookByPublicidDelete	DELETE /webhook/{publicid}	Delete Webhook
WebhookService	webhookByPublicidGet	GET /webhook/{publicid}	Load Webhook
WebhookService	webhookByPublicidPut	PUT /webhook/{publicid}	Update Webhook
WebhookService	webhookByPublicidSecretRotatePost	POST /webhook/{publicid}/secret/rotate	Rotate Webhook Secret
WebhookService	webhookGet	GET /webhook	Load Webhooks
WebhookService	webhookPost	POST /webhook	Add Webhook

Models

All models are TypeScript interfaces (or as const enums) exported from the package root.

Show all 99 models

Building from source

npm install
npm run build

npm run build packages the library into dist/ with ng-packagr. To publish, run npm publish dist (note the dist folder).

Versioning

The SDK follows the Elastic Email API v4. Package versions are listed on npm and release notes in GitHub Releases.

Build details

API version: 4.0.0
SDK version: 4.4.0
Build package: org.openapitools.codegen.languages.TypeScriptAngularClientCodegen

Contributing

Contributions are welcome! Most of this SDK is generated by OpenAPI Generator from the Elastic Email API specification, so please read CONTRIBUTING.md before opening a pull request.

This project follows the Contributor Covenant Code of Conduct.

Support

Important

The fastest way to get help is the chat widget on elasticemail.com. Our support team can help with your account, sending, deliverability and API questions.

💬 Chat with support on elasticemail.com (preferred)
📚 API documentation
🧪 Examples repository
🐛 GitHub issues, for bugs in this SDK only

Name		Name	Last commit message	Last commit date
.github		.github
api		api
model		model
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VERSION		VERSION
api.module.ts		api.module.ts
configuration.ts		configuration.ts
encoder.ts		encoder.ts
index.ts		index.ts
ng-package.json		ng-package.json
package.json		package.json
param.ts		param.ts
tsconfig.json		tsconfig.json
variables.ts		variables.ts

Navigation Menu

Repository navigation

About

Repository files navigation

Elastic Email Angular SDK

Features

Requirements

Installation

Quick start

Configure the client

Send a transactional email

Retry a send safely (Idempotency-Key)

Send from a template with merge fields

Call through your own backend

Timeouts and headers

Create a signed webhook

More examples

Authentication

API limits

API reference

Models

Building from source

Versioning

Contributing

Support

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Elastic Email Angular SDK

Features

Requirements

Installation

Quick start

Configure the client

Send a transactional email

Retry a send safely (Idempotency-Key)

Send from a template with merge fields

Call through your own backend

Timeouts and headers

Create a signed webhook

More examples

Authentication

API limits

API reference

Models

Building from source

Versioning

Contributing

Support

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages