--- title: Email Transport description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Email Transport --- # Email Transport Endpoints for receiving email transport webhook events for audit trail processing. ## Ingest email transport webhook events{% #ingest-email-transport-webhook-events %} {% tab title="v2" %} **Note**: This endpoint is in preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/). | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------------ | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/email/transport/webhook_intake | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/email/transport/webhook_intake | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/email/transport/webhook_intake | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/email/transport/webhook_intake | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/email/transport/webhook_intake | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/email/transport/webhook_intake | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/email/transport/webhook_intake | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/email/transport/webhook_intake | ### Overview Receives a batch of email transport webhook log events and emits an audit trail entry for each event with a final delivery status (delivered, dropped, or bounced). Only authorized organizations can submit events. ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | | attributes | object | Top-level attributes for the webhook log event, including delivery status, recipient details, and provider metadata. | | attributes | category | [string] | The event categories. | | attributes | email | object | The email address details. | | email | address | string | The recipient email address. | | email | domain | string | The recipient domain. | | email | subject | string | The email subject line. | | email | type | [string] | Email categorization tags applied by the transport provider (for example, "transactional", "marketing"). | | attributes | email_id | string | The unique email identifier. | | attributes | email_type_display_name | string | The human-readable email type name. | | attributes | message | object | The message delivery event details. | | message | auth | object | The message authentication details. | | auth | delivered_with_tls | string | The TLS version or negotiation information. | | message | custom_args | object | Custom arguments passed through the email transport provider for tracking. | | custom_args | email_id | string | The unique email identifier. | | custom_args | email_type_display_name | string | The human-readable email type name. | | custom_args | org_uuid | string | The organization UUID. | | custom_args | queue_time | string | The timestamp when the email was queued. | | custom_args | subject | string | The email subject line. | | message | id | object | The message identifiers. | | id | message_id | string | The RFC 5322 Message-ID. | | id | smtp_id | string | The SMTP transaction identifier. | | id | transport_event_id | string | The transport provider event identifier. | | message | name | string | The delivery event type emitted by the transport provider (for example, "delivered", "dropped", "bounced"). | | message | response | object | The SMTP response information. | | response | enhanced_smtp_code | string | The enhanced SMTP status code. | | response | reason | string | The SMTP response message. | | response | smtp_code | string | The SMTP status code. | | message | sender_ip | string | The IP address of the sending server. | | message | timestamp | object | The message delivery timing information. | | timestamp | event_timestamp | double | The Unix timestamp of the event. | | timestamp | lifetime | double | The total delivery time in seconds. | | timestamp | queue_time | double | Number of seconds the message spent in the delivery queue. | | timestamp | scheduled_time | double | The scheduled delivery time as a Unix timestamp. | | attributes | network | object | The network information for the event. | | network | ip | object | The IP address information. | | ip | attributes | [object] | Per-IP attribute records, each pairing an IP address with the providers that observed it. | | attributes | ip | string | The IP address. | | attributes | source | [string] | The transport providers or systems that reported this IP address. | | ip | list | [string] | The list of IP addresses. | | attributes | org | int64 | The numeric organization identifier. | | attributes | org_metadata | object | Metadata about the organization that sent the email. | | org_metadata | billing_country | string | Country code or name used for billing purposes. | | org_metadata | billing_plan | string | The Datadog billing plan for the organization (for example, "pro", "enterprise"). | | org_metadata | customer_tier | string | Support or account tier assigned to the organization (for example, "tier-1"). | | org_metadata | domain | string | Primary email domain associated with the organization (for example, "example.com"). | | org_metadata | industry | string | Industry classification of the organization (for example, "technology", "finance"). | | org_metadata | is_bugbounty | string | Whether the organization is enrolled in the Datadog bug bounty program. | | org_metadata | is_msp | string | Whether the organization operates as a Managed Service Provider managing child orgs. | | org_metadata | name | string | Display name of the organization as configured in Datadog account settings. | | org_metadata | org_uuid | string | Globally unique identifier for the Datadog organization (UUID v1 format). | | org_metadata | parent_org_id | string | Identifier of the immediate parent organization, if this is a child org. | | org_metadata | premium_support | string | Whether the organization has a premium support plan with Datadog. | | org_metadata | root_org_id | string | Identifier of the top-level parent organization in a multi-org account hierarchy. | | org_metadata | root_org_name | string | Display name of the top-level parent organization in a multi-org account hierarchy. | | org_metadata | shipping_country | string | Country code or name used for shipping or regional assignment. | | org_metadata | website | string | Website URL provided during organization registration. | | org_metadata | when_created | string | ISO 8601 timestamp of when the Datadog organization was created. | | attributes | org_uuid | string | The organization UUID. | | attributes | queue_time | string | The timestamp when the email was queued. | | attributes | sg_machine_open | boolean | Indicates whether the open event was triggered by automated machine activity rather than a human recipient (SendGrid-specific). | | attributes | subject | string | The email subject line. | | attributes | useragent | string | The user agent string for open events. | | | date | date-time | The ISO 8601 timestamp of the event. | | | log_id | string | The unique log event identifier. | | | source | string | The email transport provider. | | | status | string | The log status level. | | | tags | [string] | A list of tags associated with the event. | {% /tab %} {% tab title="Example" %} ```json { "attributes": { "category": [ "transactional" ], "email": { "address": "user@example.com", "domain": "example.com", "subject": "[Monitor Alert] CPU usage is high", "type": [ "transactional" ] }, "email_id": "abc123-def456", "email_type_display_name": "Monitor Alert", "message": { "auth": { "delivered_with_tls": "TLSv1.2" }, "custom_args": { "email_id": "abc123-def456", "email_type_display_name": "Monitor Alert", "org_uuid": "8dee7c38-00cb-11ea-a77b-8b5a08d3b091", "queue_time": "2024-01-15T10:29:00Z", "subject": "[Monitor Alert] CPU usage is high" }, "id": { "message_id": "", "smtp_id": "", "transport_event_id": "evt_abc123" }, "name": "delivered", "response": { "enhanced_smtp_code": "2.0.0", "reason": "250 2.0.0 OK", "smtp_code": "250" }, "sender_ip": "192.168.1.1", "timestamp": { "event_timestamp": 1705312200, "lifetime": 3.2, "queue_time": 1.5, "scheduled_time": 1705312190 } }, "network": { "ip": { "attributes": [ { "ip": "192.168.1.1", "source": [ "sendgrid" ] } ], "list": [ "192.168.1.1" ] } }, "org": 1234, "org_metadata": { "billing_country": "string", "billing_plan": "string", "customer_tier": "string", "domain": "string", "industry": "string", "is_bugbounty": "string", "is_msp": "string", "name": "string", "org_uuid": "string", "parent_org_id": "string", "premium_support": "string", "root_org_id": "string", "root_org_name": "string", "shipping_country": "string", "website": "string", "when_created": "string" }, "org_uuid": "8dee7c38-00cb-11ea-a77b-8b5a08d3b091", "queue_time": "2024-01-15T10:29:00Z", "sg_machine_open": false, "subject": "[Monitor Alert] CPU usage is high", "useragent": "Mozilla/5.0" }, "date": "2024-01-15T10:30:00Z", "log_id": "AQAAAZPHnBT0TwJAdgAAAABBWlBIblVlNEFBQ0dFMmVkYTFDSnRR", "source": "sendgrid", "status": "info", "tags": [ "env:production" ] } ``` {% /tab %} ### Response {% tab title="204" %} No Content {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Curl commandcurl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/email/transport/webhook_intake" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF [ { "attributes": { "email": { "address": "user@example.com", "domain": "example.com" }, "email_id": "abc123-def456", "email_type_display_name": "Monitor Alert", "message": { "id": { "message_id": "\u003cmessage-id@example.com\u003e", "smtp_id": "\u003cabc123@mail.example.com\u003e" }, "name": "delivered", "response": { "reason": "250 2.0.0 OK", "smtp_code": "250" }, "timestamp": { "event_timestamp": 1705312200 } }, "org": 1234, "org_uuid": "8dee7c38-00cb-11ea-a77b-8b5a08d3b091", "subject": "[Monitor Alert] CPU usage is high" }, "date": "2024-01-15T10:30:00Z", "log_id": "AQAAAZPHnBT0TwJAdgAAAABBWlBIblVlNEFBQ0dFMmVkYTFDSnRR", "source": "sendgrid", "status": "info", "tags": [ "env:production" ] } ] EOF {% /tab %}