# Railmail

## Docs

- [Get the AI credit balance](https://docs.railmail.app/api-reference/ai-credits/get-the-ai-credit-balance.md): Requires scope: `credits:read`. Tenancy: resolved from the API key's tenant to its organization.
- [List AI credit transactions](https://docs.railmail.app/api-reference/ai-credits/list-ai-credit-transactions.md): Returns the account's credit transactions, paginated. Requires scope: `credits:read`. Tenancy: resolved from the API key's tenant to its organization.
- [Activate an automation](https://docs.railmail.app/api-reference/automations/activate-an-automation.md): Transitions the automation to `ACTIVE`. Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Create an automation](https://docs.railmail.app/api-reference/automations/create-an-automation.md): Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Delete an automation](https://docs.railmail.app/api-reference/automations/delete-an-automation.md): Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Get an automation](https://docs.railmail.app/api-reference/automations/get-an-automation.md): Requires scope: `automations:read`. Tenancy: scoped to the API key's project; an id from another project returns 404.
- [List automations](https://docs.railmail.app/api-reference/automations/list-automations.md): Lists automations in the project, newest first. Requires scope: `automations:read`. Tenancy: scoped to the API key's project.
- [Pause an automation](https://docs.railmail.app/api-reference/automations/pause-an-automation.md): Transitions the automation to `PAUSED`. Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Update an automation](https://docs.railmail.app/api-reference/automations/update-an-automation.md): Updates name, description, trigger and status. Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Update automation content](https://docs.railmail.app/api-reference/automations/update-automation-content.md): Replaces the automation graph nodes and edges. Requires scope: `automations:write`. Tenancy: scoped to the API key's project.
- [Get the account subscription](https://docs.railmail.app/api-reference/billing/get-the-account-subscription.md): Returns the subscription for the account that owns this key's tenant. Requires scope: `billing:read`. Tenancy: resolved from the API key's tenant to its organization.
- [Get the usage summary](https://docs.railmail.app/api-reference/billing/get-the-usage-summary.md): Returns current usage versus plan limits. Requires scope: `billing:read`. Tenancy: resolved from the API key's tenant to its organization.
- [List available plans](https://docs.railmail.app/api-reference/billing/list-available-plans.md): Returns the plans available to the account. Requires scope: `billing:read`. Tenancy: resolved from the API key's tenant to its organization.
- [List invoices](https://docs.railmail.app/api-reference/billing/list-invoices.md): Returns the account's invoices, paginated. Requires scope: `billing:read`. Tenancy: resolved from the API key's tenant to its organization.
- [Export statistics as CSV](https://docs.railmail.app/api-reference/campaign-reports/export-statistics-as-csv.md): Returns the campaign statistics as a CSV file. Requires scope: `reports:read`. Tenancy: scoped to the API key's project.
- [Get live campaign statistics](https://docs.railmail.app/api-reference/campaign-reports/get-live-campaign-statistics.md): Returns live delivery and engagement statistics. Requires scope: `reports:read`. Tenancy: scoped to the API key's project.
- [Get the campaign report](https://docs.railmail.app/api-reference/campaign-reports/get-the-campaign-report.md): Returns the generated AI report and its content for a campaign. Requires scope: `reports:read`. Tenancy: scoped to the API key's project.
- [Get the statistics timeline](https://docs.railmail.app/api-reference/campaign-reports/get-the-statistics-timeline.md): Returns a time series of delivery and engagement counts. Requires scope: `reports:read`. Tenancy: scoped to the API key's project.
- [Create a campaign](https://docs.railmail.app/api-reference/campaigns/create-a-campaign.md): Creates a draft campaign. Requires scope: `campaigns:write`. Tenancy: scoped to the API key's project.
- [Delete a campaign](https://docs.railmail.app/api-reference/campaigns/delete-a-campaign.md): Requires scope: `campaigns:write`. Tenancy: scoped to the API key's project.
- [Get a campaign by key](https://docs.railmail.app/api-reference/campaigns/get-a-campaign-by-key.md): Requires scope: `campaigns:read`. Tenancy: scoped to the API key's project; a key from another project returns 404.
- [List campaigns](https://docs.railmail.app/api-reference/campaigns/list-campaigns.md): Lists campaigns in the project, newest first. Requires scope: `campaigns:read`. Tenancy: scoped to the API key's project.
- [Schedule a campaign](https://docs.railmail.app/api-reference/campaigns/schedule-a-campaign.md): Transitions the campaign to `SCHEDULED`. The campaign must define a `scheduledAt`. Requires scope: `campaigns:write`. Tenancy: scoped to the API key's project.
- [Send a campaign](https://docs.railmail.app/api-reference/campaigns/send-a-campaign.md): Queues the campaign for immediate sending (`QUEUED_FOR_SENDING`). Pre-send guards in the platform may reject the transition. Requires scope: `campaigns:write`. Tenancy: scoped to the API key's project.
- [Update a campaign](https://docs.railmail.app/api-reference/campaigns/update-a-campaign.md): Updates campaign metadata and content. Requires scope: `campaigns:write`. Tenancy: scoped to the API key's project.
- [Grant consent for a topic](https://docs.railmail.app/api-reference/consents/grant-consent-for-a-topic.md): Subscribes an existing subscriber to a topic. If the topic uses double opt-in, the consent is created `PENDING_CONFIRMATION` (`requiresConfirmation: true`) and the subscriber must confirm via email before they are subscribed. Requires scope: `consents:manage`. Tenancy: scoped to the API key's projec…
- [List a subscriber's consents](https://docs.railmail.app/api-reference/consents/list-a-subscribers-consents.md): Returns per-topic consent status and whether the subscriber is globally suppressed. Requires scope: `consents:manage`. Tenancy: scoped to the API key's project.
- [Revoke consent for a topic](https://docs.railmail.app/api-reference/consents/revoke-consent-for-a-topic.md): Unsubscribes the subscriber from a single topic (not a global unsubscribe). Requires scope: `consents:manage`. Tenancy: scoped to the API key's project.
- [Archive a custom field](https://docs.railmail.app/api-reference/custom-fields/archive-a-custom-field.md): Archives (soft-deletes) the custom field. Requires scope: `custom_fields:write`. Tenancy: scoped to the API key's project.
- [Create a custom field](https://docs.railmail.app/api-reference/custom-fields/create-a-custom-field.md): Creates a custom field definition. SELECT and MULTI_SELECT require `options`. Requires scope: `custom_fields:write`. Tenancy: scoped to the API key's project.
- [Get a custom field by key](https://docs.railmail.app/api-reference/custom-fields/get-a-custom-field-by-key.md): Requires scope: `custom_fields:read`. Tenancy: scoped to the API key's project.
- [List active custom fields](https://docs.railmail.app/api-reference/custom-fields/list-active-custom-fields.md): Lists active custom field definitions in the project. Requires scope: `custom_fields:read`. Tenancy: scoped to the API key's project.
- [Update custom field config](https://docs.railmail.app/api-reference/custom-fields/update-custom-field-config.md): Updates the field's config (e.g. SELECT options) and default value. Requires scope: `custom_fields:write`. Tenancy: scoped to the API key's project.
- [Update custom field details](https://docs.railmail.app/api-reference/custom-fields/update-custom-field-details.md): Updates display name, description and required flag. Requires scope: `custom_fields:write`. Tenancy: scoped to the API key's project.
- [Get the current project](https://docs.railmail.app/api-reference/project/get-the-current-project.md): Returns the project the API key is scoped to. Project creation and deletion are not exposed over the public API. Requires scope: `projects:read`. Tenancy: scoped to the API key's project.
- [Add members to a segment](https://docs.railmail.app/api-reference/segments/add-members-to-a-segment.md): Adds subscribers (by id) to a static segment. Requires scope: `segments:write`. Tenancy: scoped to the API key's project.
- [Create a segment](https://docs.railmail.app/api-reference/segments/create-a-segment.md): Requires scope: `segments:write`. Tenancy: scoped to the API key's project.
- [Delete a segment](https://docs.railmail.app/api-reference/segments/delete-a-segment.md): Requires scope: `segments:write`. Tenancy: scoped to the API key's project.
- [Get a segment](https://docs.railmail.app/api-reference/segments/get-a-segment.md): Requires scope: `segments:read`. Tenancy: scoped to the API key's project; an id from another project returns 404.
- [List segment members](https://docs.railmail.app/api-reference/segments/list-segment-members.md): Requires scope: `segments:read`. Tenancy: scoped to the API key's project.
- [List segments](https://docs.railmail.app/api-reference/segments/list-segments.md): Lists segments in the project, newest first. Requires scope: `segments:read`. Tenancy: scoped to the API key's project.
- [Remove members from a segment](https://docs.railmail.app/api-reference/segments/remove-members-from-a-segment.md): Removes subscribers (by id) from a static segment. Requires scope: `segments:write`. Tenancy: scoped to the API key's project.
- [Update a segment](https://docs.railmail.app/api-reference/segments/update-a-segment.md): Requires scope: `segments:write`. Tenancy: scoped to the API key's project.
- [Get DNS setup instructions](https://docs.railmail.app/api-reference/sending-domain/get-dns-setup-instructions.md): Returns the DNS records that must be added to verify the domain. Requires scope: `sending_domains:read`. Tenancy: scoped to the API key's project.
- [Get the project's sending domain](https://docs.railmail.app/api-reference/sending-domain/get-the-projects-sending-domain.md): Each project has at most one custom sending domain. Requires scope: `sending_domains:read`. Tenancy: scoped to the API key's project.
- [Remove the custom sending domain](https://docs.railmail.app/api-reference/sending-domain/remove-the-custom-sending-domain.md): Requires scope: `sending_domains:write`. Tenancy: scoped to the API key's project.
- [Set up a custom sending domain](https://docs.railmail.app/api-reference/sending-domain/set-up-a-custom-sending-domain.md): Sets up a custom sending domain for the project. Requires scope: `sending_domains:write`. Tenancy: the tenant is taken from the API key context, never the body.
- [Update the sending domain](https://docs.railmail.app/api-reference/sending-domain/update-the-sending-domain.md): Updates the custom sending domain name. Requires scope: `sending_domains:write`. Tenancy: scoped to the API key's project.
- [Verify the domain's DNS records](https://docs.railmail.app/api-reference/sending-domain/verify-the-domains-dns-records.md): Triggers a DNS verification check and returns the resulting status. Requires scope: `sending_domains:write`. Tenancy: scoped to the API key's project.
- [Create a subscriber](https://docs.railmail.app/api-reference/subscribers/create-a-subscriber.md): Creates a subscriber in the key's project and subscribes them to the given topics in a single call. If a topic uses double opt-in, the resulting consent is `PENDING_CONFIRMATION`. Requires scope: `subscribers:write`. Tenancy: scoped to the API key's project.
- [Delete a subscriber](https://docs.railmail.app/api-reference/subscribers/delete-a-subscriber.md): Requires scope: `subscribers:write`. Tenancy: scoped to the API key's project.
- [Get a subscriber by email](https://docs.railmail.app/api-reference/subscribers/get-a-subscriber-by-email.md): Requires scope: `subscribers:read`. Tenancy: scoped to the API key's project; an email from another project returns 404.
- [List subscribers](https://docs.railmail.app/api-reference/subscribers/list-subscribers.md): Lists subscribers in the project, newest first. Requires scope: `subscribers:read`. Tenancy: scoped to the API key's project.
- [Update a subscriber](https://docs.railmail.app/api-reference/subscribers/update-a-subscriber.md): Updates name, phone and custom fields. Requires scope: `subscribers:write`. Tenancy: scoped to the API key's project.
- [Add an email to the suppression list](https://docs.railmail.app/api-reference/suppressions/add-an-email-to-the-suppression-list.md): Suppresses an email so it can no longer receive any mail. Requires scope: `suppressions:manage`. Tenancy: scoped to the API key's project.
- [Check whether an email is suppressed](https://docs.railmail.app/api-reference/suppressions/check-whether-an-email-is-suppressed.md): Requires scope: `suppressions:manage`. Tenancy: scoped to the API key's project.
- [Remove an email from the suppression list](https://docs.railmail.app/api-reference/suppressions/remove-an-email-from-the-suppression-list.md): Removing a global unsubscribe is irreversible-sensitive, so it requires the confirmation header `X-Confirm-Unsuppress: true`. Requires scope: `suppressions:manage`. Tenancy: scoped to the API key's project.
- [Create a topic](https://docs.railmail.app/api-reference/topics/create-a-topic.md): Requires scope: `topics:write`. Tenancy: scoped to the API key's project.
- [Delete a topic](https://docs.railmail.app/api-reference/topics/delete-a-topic.md): Requires scope: `topics:write`. Tenancy: scoped to the API key's project.
- [Get a topic by key](https://docs.railmail.app/api-reference/topics/get-a-topic-by-key.md): Requires scope: `topics:read`. Tenancy: scoped to the API key's project; a key from another project returns 404.
- [List topics](https://docs.railmail.app/api-reference/topics/list-topics.md): Lists subscription topics in the project. Requires scope: `topics:read`. Tenancy: scoped to the API key's project.
- [Update a topic](https://docs.railmail.app/api-reference/topics/update-a-topic.md): Requires scope: `topics:write`. Tenancy: scoped to the API key's project.
- [Authentication](https://docs.railmail.app/en/api-reference/authentication.md): Authenticate every request with a project-scoped API key and the right scopes.
- [Errors](https://docs.railmail.app/en/api-reference/errors.md): Railmail returns RFC 7807 problem details for every error.
- [Introduction](https://docs.railmail.app/en/api-reference/introduction.md): REST API for managing the Railmail email marketing platform programmatically.
- [Rate limits](https://docs.railmail.app/en/api-reference/rate-limits.md): Requests are limited to 60 per minute per API key.
- [Introduction](https://docs.railmail.app/en/index.md): Railmail is an email marketing platform you can drive entirely through an API.
- [Quickstart](https://docs.railmail.app/en/quickstart.md): From an API key to your first subscribed user in minutes.

## OpenAPI Specs

- [openapi.pl](https://docs.railmail.app/api-reference/openapi.pl.json)
- [openapi](https://docs.railmail.app/api-reference/openapi.json)

## Optional

- [API](https://api.railmail.app)
- [Portal](https://app.railmail.app)