diff --git a/diagrams/class-diagrams/runner.md b/diagrams/class-diagrams/runner.md
index 97d21e042..99e4f5d3f 100644
--- a/diagrams/class-diagrams/runner.md
+++ b/diagrams/class-diagrams/runner.md
@@ -7,14 +7,22 @@ title: GOV.UK Forms Runner app class diagram
```mermaid
classDiagram
- direction RL
- class `Submission`
- `Submission` : +jsonb answers
- `Submission` : +jsonb form_document
- `Submission` : +integer form_id
- `Submission` : +string mail_message_id
- `Submission` : +string mail_status
- `Submission` : +string mode
- `Submission` : +string reference
- `Submission` : +datetime sent_at
+ direction RL
+ class `Delivery`
+ `Delivery` : +datetime delivered_at
+ `Delivery` : +string delivery_reference
+ `Delivery` : +datetime failed_at
+ `Delivery` : +string failure_reason
+ `Delivery` : +datetime last_attempt_at
+ class `Submission`
+ `Submission` : +jsonb answers
+ `Submission` : +jsonb form_document
+ `Submission` : +integer form_id
+ `Submission` : +string mode
+ `Submission` : +string reference
+ `Submission` : +string submission_locale
+ class `SubmissionDelivery`
+ `Submission` --> `SubmissionDelivery`
+ `Delivery` --> `SubmissionDelivery`
+ `Submission` "0..*" -- "0..*" `Delivery`
```
diff --git a/diagrams/sequence-diagrams/sending-submission-emails.md b/diagrams/sequence-diagrams/sending-submission-emails.md
index 2af74485d..95d9684f3 100644
--- a/diagrams/sequence-diagrams/sending-submission-emails.md
+++ b/diagrams/sequence-diagrams/sending-submission-emails.md
@@ -75,8 +75,7 @@ break error
end
ses->>worker: return message_id
-worker->>runner-db: set mail_message_id on Submission
-worker->>runner-db: set the last_delivery_attempt timestamp on Submission
+worker->>runner-db: create a Delivery record with the
message_id from SES as the delivery_reference
ses-)inbox: send email
note over ses,inbox: happens some time later
@@ -116,15 +115,15 @@ worker->>solidqueue-db: enqueue recurring receive bounces job
worker->>solidqueue-db: dequeue receive bounces job
worker->>sqs: get messages from bounces and complaints queue
alt there is a bounce SQS message
- worker->>runner-db: get Submission by the message_id in the SQS message
- worker->>runner-db: update delivery_status of Submission to "bounced"
+ worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message
+ worker->>runner-db: set the failed_at timestamp on the Delivery
worker->>worker: Log with the submission details
worker->>sentry: send error event
sentry->>support: Alert via Slack
support->>support: Identify why the email bounced
support->>support: Run rake task to retry submission
else there is a complaint SQS message
- worker->>runner-db: get Submission by the message_id in the SQS message
+ worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message
worker->>worker: Log with the submission details
end
@@ -152,7 +151,8 @@ actor support as Forms team tech support
worker->>solidqueue-db: enqueue recurring receive deliveries job
worker->>solidqueue-db: dequeue receive deliveries job
worker->>sqs: get messages from deliveries queue
-worker->>runner-db: get Submission by the message_id in the SQS message
+worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message
+worker->>runner-db: set the delivered_at timestamp on the Delivery
worker->>worker: log a "form_submission_delivered" event
note over worker,runner-db: we don't currently use the "delivered" status for anything other than for information
```